HTML
Living Standard — Last Updated 8 September 2025
Living Standard — Last Updated 8 September 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 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:blankUser-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 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 Web IDL fragments in this specification:
ArrayBufferArrayBufferViewbooleanDOMStringdoubleFloat16ArrayFunctionlongobjectPromiseUint8ClampedArrayunrestricted doubleunsigned longUSVStringVoidFunctionThe 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"QuotaExceededError"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]
The 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 given in the specification of each attribute, and two possible special states that can also be given in the specification of the attribute. These special states are the invalid value default and the missing value default.
Multiple keywords can map to the same state.
The empty string can be a valid keyword. Note that the missing value default applies only when the attribute is missing, not when it is present with an empty string value.
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 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 an ASCII case-insensitive match for one of the conforming keywords for that attribute, with no leading or trailing whitespace.
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.
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 whose type is "basic", "cors", or "default" is CORS-same-origin.
[FETCH]
A response whose type is "opaque" or "opaqueredirect" is CORS-cross-origin.
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".
|
| (the empty string) | ||
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 is 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 n be index minus length.
If n is greater than zero, then append a DocumentFragment consisting of n-1 new option elements with no attributes and
no child nodes to the select element on which the HTMLOptionsCollection
is rooted.
If n 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.
The length getter steps are to return
this's associated list's size.
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.
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 ;
};
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):
accesskeyautocapitalizeautocorrectautofocuscontenteditabledirdraggableenterkeyhintinertinputmodeisitemiditempropitemrefitemscopeitemtypelangnoncepopoverspellcheckstyletabindextitletranslatewritingsuggestionsThese 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, not the "http://www.w3.org/2000/xmlns/" namespace like namespace declaration attributes in
XML do.
In XML, an xmlns attribute is part of the namespace
declaration mechanism, and an element cannot actually have an xmlns
attribute in no namespace specified.
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. |
| (the empty string) | ||
no
| No | Sets translation mode to no-translate. |
The attribute's missing value default and invalid value default are both the Inherit 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:
input elements whose type attribute is
in the , Text, Search,
Telephone, URL, Email, Password, Submit
Button, Reset Button, or Button state, and
textarea elements.
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:
If options's destination is null, then return null.
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
as attributecrossorigin
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.
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:
If attribs["as"] exists, then set options's destination to the result of translating attribs["as"].
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.
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.
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.
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 the number in the element's name.
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 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.
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 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, and
whenever those elements have their href content
attribute set, changed, or removed, the user agent must set the url.
This is only observable for blob: URLs as
parsing them involves a Blob URL Store lookup.
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:
If url is null, or url's query is either null or the empty string, return the empty string.
Return "?", followed by url's query.
The search setter steps are:
If url is null, terminate these steps.
If the given value is the empty string, set url's query to null.
Otherwise:
Let input be the given value with a single leading "?"
removed, if any.
Set url's query to the empty string.
Basic URL parse input, with url as url and query state as state override.
The hash getter steps are:
If url is null, or url's fragment is either null or the empty string, return the empty string.
Return "#", followed by url's fragment.
The hash setter steps are:
If url is null, then return.
If the given value is the empty string, set url's fragment to null.
Otherwise:
Let input be the given value with a single leading "#"
removed, if any.
Set url's fragment to the empty string.
Basic URL parse input, with url as url and fragment state as state override.
An element element cannot navigate if any of the following are true:
element's node document is not fully active; or
This is also used by form submission for
the form element. The exception for a elements is for compatibility with
web content.
To get an element's noopener, given an a, area, or
form element element, a URL record url, and a
string target, perform the following steps. They return a boolean.
If element's link types include the noopener or noreferrer
keyword, then return true.
If element's link types
do not include the opener keyword and target is an
ASCII case-insensitive match for "_blank", then return
true.
If url's blob URL entry is not null:
Let blobOrigin be url's blob URL entry's environment's origin.
Let topLevelOrigin be element's relevant settings object's top-level origin.
If blobOrigin is not same site with topLevelOrigin, then return true.
Return false.
To follow the hyperlink created by an element
subject, given an optional hyperlinkSuffix (default null) and an
optional userInvolvement (default "none"):
If subject cannot navigate, then return.
Let targetAttributeValue be the empty string.
If subject is an a or area element, then set
targetAttributeValue to the result of getting
an element's target given subject.
Let urlRecord be the result of encoding-parsing a URL given
subject's href attribute value, relative to
subject's node document.
If urlRecord is failure, then return.
Let noopener be the result of getting an element's noopener with subject, urlRecord, and targetAttributeValue.
Let targetNavigable be the first return value of applying the rules for choosing a navigable given targetAttributeValue, subject's node navigable, and noopener.
If targetNavigable is null, then return.
Let urlString be the result of applying the URL serializer to urlRecord.
If hyperlinkSuffix is non-null, then append it to urlString.
Let referrerPolicy be the current state of subject's referrerpolicy content attribute.
If subject's link
types includes the noreferrer keyword, then set
referrerPolicy to "no-referrer".
Navigate targetNavigable to urlString using subject's node document, with referrerPolicy set to referrerPolicy, userInvolvement set to userInvolvement, and sourceElement set to subject.
Unlike many other types of navigations, following hyperlinks does not have
special "replace" behavior for when
documents are not completely loaded. This is true for both user-initiated instances
of following hyperlinks, as well as script-triggered ones via, e.g., aElement.click().
Support in all current engines.
In some cases, resources are intended for later use rather than immediate viewing. To indicate
that a resource is intended to be downloaded for use later, rather than immediately used, the
download attribute can be specified on the
a or area element that creates the hyperlink to that
resource.
The attribute can furthermore be given a value, to specify the filename that user agents are
to use when storing the resource in a file system. This value can be overridden by the `Content-Disposition` HTTP header's filename parameters.
[RFC6266]
In cross-origin situations, the download
attribute has to be combined with the `Content-Disposition` HTTP header, specifically with the
attachment disposition type, to avoid the user being warned of possibly
nefarious activity. (This is to protect users from being made to download sensitive personal or
confidential information without their full understanding.)
To download the hyperlink created by an
element subject, given an optional hyperlinkSuffix (default null) and an
optional userInvolvement (default
"none"):
If subject cannot navigate, then return.
If subject's node document's active sandboxing flag set has the sandboxed downloads browsing context flag set, then return.
Let urlString be the result of encoding-parsing-and-serializing a
URL given subject's href attribute
value, relative to subject's node document.
If urlString is failure, then return.
If hyperlinkSuffix is non-null, then append it to urlString.
If userInvolvement is not "browser UI",
then:
Let navigation be subject's relevant global object's navigation API.
Let filename be the value of subject's download attribute.
Let continue be the result of firing a download request navigate event at
navigation with destinationURL
set to urlString, userInvolvement set to
userInvolvement, sourceElement
set to subject, and filename set to
filename.
If continue is false, then return.
Run these steps in parallel:
Optionally, the user agent may abort these steps, if it believes doing so would safeguard the user from a potentially hostile download.
Let request be a new request whose
URL is urlString, client is entry settings object, initiator is "download", destination is the empty string, and whose
synchronous flag and use-URL-credentials flag are set.
Handle as a download the result of fetching request.
To handle as a download a response response:
Let suggestedFilename be the result of getting the suggested filename for response.
Provide the user with a way to save response for later use. If the user agent needs a filename, it should use suggestedFilename. Report any problems downloading the file to the user.
Return suggestedFilename.
To get the suggested filename for a response response:
This algorithm is intended to mitigate security dangers involved in downloading files from untrusted sites, and user agents are strongly urged to follow it.
Let filename be the undefined value.
If response has a `Content-Disposition` header, that header specifies the
attachment disposition type, and the header includes filename information,
then let filename have the value specified by the header, and jump to the step labeled
sanitize below. [RFC6266]
Let interface origin be the origin of the Document in which the download or navigate action resulting in the
download was initiated, if any.
Let response origin be the origin of the URL of
response, unless that URL's scheme component
is data, in which case let response origin be the same as the
interface origin, if any.
If there is no interface origin, then let trusted operation be true. Otherwise, let trusted operation be true if response origin is the same origin as interface origin, and false otherwise.
If trusted operation is true and response has a `Content-Disposition` header and that header includes
filename information, then let filename have the value specified by the header, and
jump to the step labeled sanitize below. [RFC6266]
If the download was not initiated from a hyperlink created by an
a or area element, or if the element of the hyperlink from
which it was initiated did not have a download
attribute when the download was initiated, or if there was such an attribute but its value when
the download was initiated was the empty string, then jump to the step labeled no proposed
filename.
Let proposed filename have the value of the download attribute of the element of the
hyperlink that initiated the download at the time the download was
initiated.
If trusted operation is true, let filename have the value of proposed filename, and jump to the step labeled sanitize below.
If response has a `Content-Disposition` header and that header specifies
the attachment disposition type, let filename have the value of
proposed filename, and jump to the step labeled sanitize below.
[RFC6266]
No proposed filename: If trusted operation is true, or if the user indicated a preference for having the response in question downloaded, let filename have a value derived from the URL of response in an implementation-defined manner, and jump to the step labeled sanitize below.
Let filename be set to the user's preferred filename or to a filename selected by the user agent, and jump to the step labeled sanitize below.
If the algorithm reaches this step, then a download was begun from a different origin than
response, and the origin did not mark the file as suitable for downloading, and the
download was not initiated by the user. This could be because a download attribute was used to trigger the download, or
because response is not of a type that the user agent supports.
This could be dangerous, because, for instance, a hostile server could be trying to get a user to unknowingly download private information and then re-upload it to the hostile server, by tricking the user into thinking the data is from the hostile server.
Thus, it is in the user's interests that the user be somehow notified that response comes from quite a different source, and to prevent confusion, any suggested filename from the potentially hostile interface origin should be ignored.
Sanitize: Optionally, allow the user to influence filename. For example, a user agent could prompt the user for a filename, potentially providing the value of filename as determined above as a default value.
Adjust filename to be suitable for the local file system.
For example, this could involve removing characters that are not legal in filenames, or trimming leading and trailing whitespace.
If the platform conventions do not in any way use extensions to determine the types of file on the file system, then return filename as the filename.
Let claimed type be the type given by response's Content-Type metadata, if any is known. Let named type be the type given by filename's extension, if any is known. For the purposes of this step, a type is a mapping of a MIME type to an extension.
If named type is consistent with the user's preferences (e.g., because the value of filename was determined by prompting the user), then return filename as the filename.
If claimed type and named type are the same type (i.e., the type given by response's Content-Type metadata is consistent with the type given by filename's extension), then return filename as the filename.
If the claimed type is known, then alter filename to add an extension corresponding to claimed type.
Otherwise, if named type is known to be potentially dangerous (e.g. it
will be treated by the platform conventions as a native executable, shell script, HTML
application, or executable-macro-capable document), then optionally alter filename to add a known-safe extension
(e.g. ".txt").
This last step would make it impossible to download executables, which might not be desirable. As always, implementers are forced to balance security and usability in this matter.
Return filename as the filename.
For the purposes of this algorithm, a file extension
consists of any part of the filename that platform conventions dictate will be used for
identifying the type of the file. For example, many operating systems use the part of the filename
following the last dot (".") in the filename to determine the type of the
file, and from that the manner in which the file is to be opened or executed.
User agents should ignore any directory or path information provided by the response itself,
its URL, and any download attribute, in
deciding where to store the resulting file in the user's file system.
If a hyperlink created by an a or area element has a
ping attribute, and the user follows the hyperlink, and
the value of the element's href attribute can be parsed, relative to the element's node
document, without failure, then the user agent must take the ping attribute's value, split that string on ASCII whitespace, parse each resulting token, relative to the element's node document, and
then run these steps for each resulting URL ping URL, ignoring when
parsing returns failure:
If ping URL's scheme is not an HTTP(S) scheme, then return.
Optionally, return. (For example, the user agent might wish to ignore any or all ping URLs in accordance with the user's expressed preferences.)
Let settingsObject be the element's node document's relevant settings object.
Let request be a new request whose URL is ping URL, method is `POST`, header list is « (`Content-Type`,
`text/ping`) », body is `PING`, client is
settingsObject, destination is the
empty string, credentials mode is "include", referrer is "no-referrer", and whose use-URL-credentials flag is set, and whose
initiator type is "ping".
Let target URL be the result of encoding-parsing-and-serializing a
URL given the element's href attribute's value,
relative to the element's node document, and then:
Document object
containing the hyperlink being audited and ping URL have the same
originDocument containing the
hyperlink being audited is not "https"Ping-From` header with, as its value, the
URL of the document containing the hyperlink, and a
`Ping-To` HTTP header with, as its value, the target URL.Ping-To` HTTP header with, as its value,
target URL. request does not include a
`Ping-From` header.Fetch request.
This may be done in parallel with the primary fetch, and is independent of the result of that fetch.
User agents should allow the user to adjust this behavior, for example in conjunction with a
setting that disables the sending of HTTP `Referer` (sic)
headers. Based on the user's preferences, UAs may either ignore the ping attribute altogether, or selectively ignore URLs in the
list (e.g. ignoring any third-party URLs); this is explicitly accounted for in the steps
above.
User agents must ignore any entity bodies returned in the responses. User agents may close the connection prematurely once they start receiving a response body.
An
a or area element that creates a hyperlink and has
the ping attribute is present, user agents may indicate
to the user that following the hyperlink will also cause secondary requests to be sent in the
background, possibly including listing the actual target URLs.
For example, a visual user agent could include the hostnames of the target ping URLs along with the hyperlink's actual URL in a status bar or tooltip.
The ping attribute is redundant with pre-existing
technologies like HTTP redirects and JavaScript in allowing web pages to track which off-site
links are most popular or allowing advertisers to track click-through rates.
However, the ping attribute provides these advantages
to the user over those alternatives:
Ping-From` and `Ping-To` headersThe `Ping-From` and `Ping-To` HTTP request headers are included in hyperlink
auditing requests. Their value is a URL, serialized.
Support in all current engines.
The following table summarizes the link types that are defined by this specification, by their corresponding keywords. This table is non-normative; the actual definitions for the link types are given in the next few sections.
In this section, the term referenced document refers to the resource identified by the element representing the link, and the term current document refers to the resource within which the element representing the link finds itself.
To determine which link types apply to a link, a, area,
or form element, the element's rel attribute must be split on ASCII whitespace. The resulting tokens
are the keywords for the link types that apply to that element.
Except where otherwise specified, a keyword must not be specified more than once per rel attribute.
Some of the sections that follow the table below list synonyms for certain keywords. The
indicated synonyms are to be handled as specified by user agents, but must
not be used in documents (for example, the keyword "copyright").
Keywords are always ASCII case-insensitive, and must be compared as such.
Thus, rel="next" is the same as rel="NEXT".
Keywords that are body-ok affect whether link elements are
allowed in the body. The body-ok keywords are
dns-prefetch,
modulepreload,
pingback,
preconnect,
prefetch,
preload, and
stylesheet.
New link types that are to be implemented by web browsers are to be added to this standard. The remainder can be registered as extensions.
| Link type | Effect on... | body-ok | Has `Link` processing | Brief description | ||
|---|---|---|---|---|---|---|
link | a and area | form | ||||
alternate | Hyperlink | not allowed | · | · | Gives alternate representations of the current document. | |
canonical | Hyperlink | not allowed | · | · | Gives the preferred URL for the current document. | |
author | Hyperlink | not allowed | · | · | Gives a link to the author of the current document or article. | |
bookmark | not allowed | Hyperlink | not allowed | · | · | Gives the permalink for the nearest ancestor section. |
dns-prefetch | External Resource | not allowed | Yes | · | Specifies that the user agent should preemptively perform DNS resolution for the target resource's origin. | |
expect | Internal Resource | not allowed | · | · | Expect an element with the target ID to appear in the current document. | |
external | not allowed | Annotation | · | · | Indicates that the referenced document is not part of the same site as the current document. | |
help | Hyperlink | · | · | Provides a link to context-sensitive help. | ||
icon | External Resource | not allowed | · | · | Imports an icon to represent the current document. | |
manifest | External Resource | not allowed | · | · | Imports or links to an application manifest. [MANIFEST] | |
modulepreload | External Resource | not allowed | Yes | · | Specifies that the user agent must preemptively fetch the module script and store it in the document's module map for later evaluation. Optionally, the module's dependencies can be fetched as well. | |
license | Hyperlink | · | · | Indicates that the main content of the current document is covered by the copyright license described by the referenced document. | ||
next | Hyperlink | · | · | Indicates that the current document is a part of a series, and that the next document in the series is the referenced document. | ||
nofollow | not allowed | Annotation | · | · | Indicates that the current document's original author or publisher does not endorse the referenced document. | |
noopener | not allowed | Annotation | · | · | Creates a top-level traversable with a non-auxiliary browsing
context if the hyperlink would otherwise create one that was auxiliary (i.e., has an
appropriate target attribute value). | |
noreferrer | not allowed | Annotation | · | · | No `Referer` (sic) header will be included.
Additionally, has the same effect as noopener. | |
opener | not allowed | Annotation | · | · | Creates an auxiliary browsing context if the hyperlink would otherwise create
a top-level traversable with a non-auxiliary browsing context (i.e.,
has "_blank" as target
attribute value). | |
pingback | External Resource | not allowed | Yes | · | Gives the address of the pingback server that handles pingbacks to the current document. | |
preconnect | External Resource | not allowed | Yes | Yes | Specifies that the user agent should preemptively connect to the target resource's origin. | |
prefetch | External Resource | not allowed | Yes | · | Specifies that the user agent should preemptively fetch and cache the target resource as it is likely to be required for a followup navigation. | |
preload | External Resource | not allowed | Yes | Yes | Specifies that the user agent must preemptively fetch and cache the target resource for current navigation according to the potential destination given by the as attribute (and the priority associated with the corresponding destination). | |
prev | Hyperlink | · | · | Indicates that the current document is a part of a series, and that the previous document in the series is the referenced document. | ||
privacy-policy | Hyperlink | not allowed | · | · | Gives a link to information about the data collection and usage practices that apply to the current document. | |
search | Hyperlink | · | · | Gives a link to a resource that can be used to search through the current document and its related pages. | ||
stylesheet | External Resource | not allowed | Yes | · | Imports a style sheet. | |
tag | not allowed | Hyperlink | not allowed | · | · | Gives a tag (identified by the given address) that applies to the current document. |
terms-of-service | Hyperlink | not allowed | · | · | Gives a link to information about the agreements between the current document's provider and users who wish to use the current document. | |
alternate"Support in one engine only.
The alternate keyword may be used with link,
a, and area elements.
The meaning of this keyword depends on the values of the other attributes.
link element and the rel
attribute also contains the keyword stylesheetThe alternate keyword modifies the meaning of the stylesheet keyword in the way described for that keyword. The
alternate keyword does not create a link of its own.
Here, a set of link elements provide some style sheets:
<!-- a persistent style sheet -->
< link rel = "stylesheet" href = "default.css" >
<!-- the preferred alternate style sheet -->
< link rel = "stylesheet" href = "green.css" title = "Green styles" >
<!-- some alternate style sheets -->
< link rel = "alternate stylesheet" href = "contrast.css" title = "High contrast" >
< link rel = "alternate stylesheet" href = "big.css" title = "Big fonts" >
< link rel = "alternate stylesheet" href = "wide.css" title = "Wide screen" > alternate keyword is used with the type attribute set to the value application/rss+xml or the value application/atom+xmlThe keyword creates a hyperlink referencing a syndication feed (though not necessarily syndicating exactly the same content as the current page).
For the purposes of feed autodiscovery, user agents should consider all link
elements in the document with the alternate keyword used and
with their type attribute set to the value application/rss+xml or the value application/atom+xml. If the user agent has the concept of a default
syndication feed, the first such element (in tree order) should be used as the
default.
The following link elements give syndication feeds for a blog:
< link rel = "alternate" type = "application/atom+xml" href = "posts.xml" title = "Cool Stuff Blog" >
< link rel = "alternate" type = "application/atom+xml" href = "posts.xml?category=robots" title = "Cool Stuff Blog: robots category" >
< link rel = "alternate" type = "application/atom+xml" href = "comments.xml" title = "Cool Stuff Blog: Comments" > Such link elements would be used by user agents engaged in feed autodiscovery,
with the first being the default (where applicable).
The following example offers various different syndication feeds to the user, using
a elements:
< p > You can access the planets database using Atom feeds:</ p >
< ul >
< li >< a href = "recently-visited-planets.xml" rel = "alternate" type = "application/atom+xml" > Recently Visited Planets</ a ></ li >
< li >< a href = "known-bad-planets.xml" rel = "alternate" type = "application/atom+xml" > Known Bad Planets</ a ></ li >
< li >< a href = "unexplored-planets.xml" rel = "alternate" type = "application/atom+xml" > Unexplored Planets</ a ></ li >
</ ul > These links would not be used in feed autodiscovery.
The keyword creates a hyperlink referencing an alternate representation of the current document.
The nature of the referenced document is given by the hreflang, and type attributes.
If the alternate keyword is used with the hreflang attribute, and that attribute's value differs
from the document element's language, it indicates that the referenced
document is a translation.
If the alternate keyword is used with the type attribute, it indicates that the referenced document is
a reformulation of the current document in the specified format.
The hreflang and type attributes can be combined when specified with the alternate keyword.
The following example shows how you can specify versions of the page that use alternative formats, are aimed at other languages, and that are intended for other media:
< link rel = alternate href = "/en/html" hreflang = en type = text/html title = "English HTML" >
< link rel = alternate href = "/fr/html" hreflang = fr type = text/html title = "French HTML" >
< link rel = alternate href = "/en/html/print" hreflang = en type = text/html media = print title = "English HTML (for printing)" >
< link rel = alternate href = "/fr/html/print" hreflang = fr type = text/html media = print title = "French HTML (for printing)" >
< link rel = alternate href = "/en/pdf" hreflang = en type = application/pdf title = "English PDF" >
< link rel = alternate href = "/fr/pdf" hreflang = fr type = application/pdf title = "French PDF" > This relationship is transitive — that is, if a document links to two other documents
with the link type "alternate", then, in addition to implying
that those documents are alternative representations of the first document, it is also implying
that those two documents are alternative representations of each other.
author"The author keyword may be used with link,
a, and area elements. This keyword creates a hyperlink.
For a and area elements, the author
keyword indicates that the referenced document provides further information about the author of
the nearest article element ancestor of the element defining the hyperlink, if there
is one, or of the page as a whole, otherwise.
For link elements, the author keyword indicates
that the referenced document provides further information about the author for the page as a
whole.
The "referenced document" can be, and often is, a mailto: URL giving the email address of the author. [MAILTO]
Synonyms: For historical reasons, user agents must also treat
link, a, and area elements that have a rev attribute with the value "made" as having the author keyword specified as a link relationship.
bookmark"The bookmark keyword may be used with a and
area elements. This keyword creates a hyperlink.
The bookmark keyword gives a permalink for the nearest
ancestor article element of the linking element in question, or of
the section the linking element is most closely associated with, if
there are no ancestor article elements.
The following snippet has three permalinks. A user agent could determine which permalink applies to which part of the spec by looking at where the permalinks are given.
...
< body >
< h1 > Example of permalinks</ h1 >
< div id = "a" >
< h2 > First example</ h2 >
< p >< a href = "a.html" rel = "bookmark" > This permalink applies to
only the content from the first H2 to the second H2</ a > . The DIV isn't
exactly that section, but it roughly corresponds to it.</ p >
</ div >
< h2 > Second example</ h2 >
< article id = "b" >
< p >< a href = "b.html" rel = "bookmark" > This permalink applies to
the outer ARTICLE element</ a > (which could be, e.g., a blog post).</ p >
< article id = "c" >
< p >< a href = "c.html" rel = "bookmark" > This permalink applies to
the inner ARTICLE element</ a > (which could be, e.g., a blog comment).</ p >
</ article >
</ article >
</ body >
...canonical"The canonical keyword may be used with link
element. This keyword creates a hyperlink.
The canonical keyword indicates that URL given by the href attribute is the preferred URL for the current document. That
helps search engines reduce duplicate content, as described in more detail in The Canonical
Link Relation. [RFC6596]
dns-prefetch"The dns-prefetch keyword may be used with
link elements. This keyword creates an external
resource link. This keyword is body-ok.
The dns-prefetch keyword indicates that preemptively
performing DNS resolution for the origin of the specified resource is likely to be
beneficial, as it is highly likely that the user will require resources located at that
origin, and the user experience would be improved by preempting the latency costs
associated with DNS resolution.
There is no default type for resources given by the dns-prefetch keyword.
The appropriate times to fetch and process this type of link are:
When the external resource link is created on a link element
that is already browsing-context connected.
When the external resource link's link element becomes
browsing-context connected.
When the href attribute of the link
element of an external resource link that is already browsing-context
connected is changed.
The fetch and process the linked resource steps for this type of linked resource,
given a link element el, are:
Let url be the result of encoding-parsing a URL given
el's href attribute's value, relative to
el's node document.
If url is failure, then return.
Let partitionKey be the result of determining the network partition key given el's node document's relevant settings object.
The user agent should resolve an origin given partitionKey and url's origin.
As the results of this algorithm can be cached, future fetches could be faster.
expect"The expect keyword may be used with link
elements. This keyword creates an internal resource
link.
An internal resource link created by the expect
keyword can be used to block rendering until the element that
it indicates is connected to the document and fully
parsed.
There is no default type for resources given by the expect
keyword.
Whenever any of the following conditions occur for a link element
el:
the expect internal resource link is created
on el that is already browsing-context connected;
an expect internal resource link has been
created on el and el becomes
browsing-context connected;
an expect internal resource link has been
created on el, el is already browsing-context connected, and
el's href attribute is set, changed, or removed;
or
an expect internal resource link has been
created on el, el is already browsing-context connected, and
el's media attribute is set, changed, or
removed,
then process el.
To process internal resource link given a link element el,
run these steps:
Let doc be el's node document.
Let url be the result of encoding-parsing a URL given
el's href attribute's value, relative to
doc.
If this fails, or if url does not equal doc's URL with exclude fragments set to false, then unblock rendering on el and return.
Let indicatedElement be the result of selecting the indicated part given doc and url.
If all of the following are true:
doc's current document readiness is "loading";
el creates an internal resource link;
el is browsing-context connected;
el is potentially render-blocking;
el's media attribute
matches the environment; and
indicatedElement is not an element, or is on a
stack of open elements of an HTML parser whose associated
Document is doc,
then block rendering on el.
Otherwise, unblock rendering on el.
To process internal resource links given a Document doc:
For each expect link element link in
doc's render-blocking element set, process link.
The following attribute change
steps, given element, localName, oldValue,
value, and namespace, are used to ensure expect link elements respond to dynamic id and name changes:
If namespace is not null, then return.
If element is in a stack of open elements of an HTML parser, then return.
If any of the following is true:
then process internal resource links given element's node document.
external"The external keyword may be used with a,
area, and form elements. This keyword does not create a
hyperlink, but annotates any other
hyperlinks created by the element (the implied hyperlink, if no other keywords create one).
The external keyword indicates that the link is leading to a
document that is not part of the site that the current document forms a part of.
help"The help keyword may be used with link,
a, area, and form elements. This keyword creates a
hyperlink.
For a, area, and form elements, the help keyword indicates that the referenced document provides further help
information for the parent of the element defining the hyperlink, and its children.
In the following example, the form control has associated context-sensitive help. The user agent could use this information, for example, displaying the referenced document if the user presses the "Help" or "F1" key.
< p >< label > Topic: < input name = topic > < a href = "help/topic.html" rel = "help" > (Help)</ a ></ label ></ p > For link elements, the help keyword indicates that
the referenced document provides help for the page as a whole.
For a and area elements, on some browsers, the help keyword causes the link to use a different cursor.
icon"Support in all current engines.
The icon keyword may be used with link elements.
This keyword creates an external resource link.
The specified resource is an icon representing the page or site, and should be used by the user agent when representing the page in the user interface.
Icons could be auditory icons, visual icons, or other kinds of icons. If
multiple icons are provided, the user agent must select the most appropriate icon according to the
type, media, and sizes attributes. If there are multiple equally appropriate icons,
user agents must use the last one declared in tree order at the time that the user
agent collected the list of icons. If the user agent tries to use an icon but that icon is
determined, upon closer examination, to in fact be inappropriate (e.g. because it uses an
unsupported format), then the user agent must try the next-most-appropriate icon as determined by
the attributes.
User agents are not required to update icons when the list of icons changes, but are encouraged to do so.
There is no default type for resources given by the icon keyword.
However, for the purposes of determining the type of the
resource, user agents must expect the resource to be an image.
The sizes keywords represent icon sizes in raw pixels (as
opposed to CSS pixels).
An icon that is 50 CSS pixels wide intended for displays with a device pixel density of two device pixels per CSS pixel (2x, 192dpi) would have a width of 100 raw pixels. This feature does not support indicating that a different resource is to be used for small high-resolution icons vs large low-resolution icons (e.g. 50×50 2x vs 100×100 1x).
To parse and process the attribute's value, the user agent must first split the attribute's value on ASCII whitespace, and must then parse each resulting keyword to determine what it represents.
The any keyword represents that the
resource contains a scalable icon, e.g. as provided by an SVG image.
Other keywords must be further parsed as follows to determine what they represent:
If the keyword doesn't contain exactly one U+0078 LATIN SMALL LETTER X or U+0058 LATIN CAPITAL LETTER X character, then this keyword doesn't represent anything. Return for that keyword.
Let width string be the string before the "x" or
"X".
Let height string be the string after the "x" or
"X".
If either width string or height string start with a U+0030 DIGIT ZERO (0) character or contain any characters other than ASCII digits, then this keyword doesn't represent anything. Return for that keyword.
Apply the rules for parsing non-negative integers to width string to obtain width.
Apply the rules for parsing non-negative integers to height string to obtain height.
The keyword represents that the resource contains a bitmap icon with a width of width device pixels and a height of height device pixels.
The keywords specified on the sizes attribute must not
represent icon sizes that are not actually available in the linked resource.
The linked resource fetch setup steps for this type of linked resource, given a
link element el and request
request, are:
Set request's destination to
"image".
Return true.
The process a link header steps for this type of linked resource are to do nothing.
In the absence of a link with the icon keyword, for
Document objects whose URL's
scheme is an HTTP(S) scheme, user agents may
instead run these steps in parallel:
Let request be a new request whose
URL is the URL record obtained by
resolving the URL "/favicon.ico" against the
Document object's URL, client is the Document object's
relevant settings object, destination is "image",
synchronous flag is set, credentials
mode is "include", and whose use-URL-credentials flag
is set.
Let response be the result of fetching request.
Use response's unsafe response as an icon as if it had been
declared using the icon keyword.
The following snippet shows the top part of an application with several icons.
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< title > lsForums — Inbox</ title >
< link rel = icon href = favicon.png sizes = "16x16" type = "image/png" >
< link rel = icon href = windows.ico sizes = "32x32 48x48" type = "image/vnd.microsoft.icon" >
< link rel = icon href = mac.icns sizes = "128x128 512x512 8192x8192 32768x32768" >
< link rel = icon href = iphone.png sizes = "57x57" type = "image/png" >
< link rel = icon href = gnome.svg sizes = "any" type = "image/svg+xml" >
< link rel = stylesheet href = lsforums.css >
< script src = lsforums.js ></ script >
< meta name = application-name content = "lsForums" >
</ head >
< body >
...For historical reasons, the icon keyword may be preceded by the
keyword "shortcut". If the "shortcut" keyword is
present, the rel attribute's entire value must be an
ASCII case-insensitive match for the string "shortcut icon" (with a single U+0020 SPACE character between the tokens and
no other ASCII whitespace).
license"The license keyword may be used with link,
a, area, and form elements. This keyword creates a
hyperlink.
The license keyword indicates that the referenced document
provides the copyright license terms under which the main content of the current document is
provided.
This specification does not specify how to distinguish between the main content of a document and content that is not deemed to be part of that main content. The distinction should be made clear to the user.
Consider a photo sharing site. A page on that site might describe and show a photograph, and the page might be marked up as follows:
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< title > Exampl Pictures: Kissat</ title >
< link rel = "stylesheet" href = "/style/default" >
</ head >
< body >
< h1 > Kissat</ h1 >
< nav >
< a href = "../" > Return to photo index</ a >
</ nav >
< figure >
< img src = "/pix/39627052_fd8dcd98b5.jpg" >
< figcaption > Kissat</ figcaption >
</ figure >
< p > One of them has six toes!</ p >
< p >< small >< a rel = "license" href = "http://www.opensource.org/licenses/mit-license.php" > MIT Licensed</ a ></ small ></ p >
< footer >
< a href = "/" > Home</ a > | < a href = "../" > Photo index</ a >
< p >< small > © copyright 2009 Exampl Pictures. All Rights Reserved.</ small ></ p >
</ footer >
</ body >
</ html > In this case the license applies to just the photo (the main
content of the document), not the whole document. In particular not the design of the page
itself, which is covered by the copyright given at the bottom of the document. This could be made
clearer in the styling (e.g. making the license link prominently positioned near the photograph,
while having the page copyright in light small text at the foot of the page).
Synonyms: For historical reasons, user agents must also treat the keyword
"copyright" like the license keyword.
manifest"Support in one engine only.
The manifest keyword may be used with link elements.
This keyword creates an external resource link.
The manifest keyword indicates the manifest file that provides
metadata associated with the current document.
There is no default type for resources given by the manifest
keyword.
When a web application is not installed, the appropriate time to fetch and process the linked resource for this link type is when the user agent deems it necessary. For example, when the user chooses to install the web application.
For an installed web application, the appropriate times to fetch and process the linked resource for this link type are:
When the external resource link is created on a link element
that is already browsing-context connected.
When the external resource link's link element becomes
browsing-context connected.
When the href attribute of the link
element of an external resource link that is already browsing-context
connected is changed.
In any case, only the first link element in tree order whose rel attribute contains the token manifest may be used.
A user agent must not delay the load event for this link type.
The linked resource fetch setup steps for this type of linked resource, given a
link element el and request
request, are:
Let navigable be el's node document's node navigable.
If navigable is null, then return false.
If navigable is not a top-level traversable, then return false.
Set request's initiator to
"manifest".
Set request's destination to
"manifest".
Set request's mode to "cors".
Set request's credentials
mode to the CORS settings attribute credentials mode for el's
crossorigin content attribute.
Return true.
To process this type of linked resource given
a link element el, boolean success, response response, and byte sequence
bodyBytes:
If response's Content-Type metadata is not a JSON MIME type, then set success to false.
If success is true:
Let document URL be el's node document's URL.
Let manifest URL be response's URL.
Process the manifest given document URL, manifest URL, and bodyBytes. [MANIFEST]
The process a link header steps for this type of linked resource are to do nothing.
modulepreload"The modulepreload keyword may be used with
link elements. This keyword creates an external resource link. This
keyword is body-ok.
The modulepreload keyword is a specialized alternative
to the preload keyword, with a processing model geared toward
preloading module scripts. In particular, it uses the specific
fetch behavior for module scripts (including, e.g., a different interpretation of the crossorigin attribute), and places the result into the
appropriate module map for later evaluation. In
contrast, a similar external resource link using the preload keyword would place the result in the preload cache, without
affecting the document's module map.
Additionally, implementations can take advantage of the fact that module scripts declare their dependencies in order to fetch the specified module's
dependency as well. This is intended as an optimization opportunity, since the user agent knows
that, in all likelihood, those dependencies will also be needed later. It will not generally be
observable without using technology such as service workers, or monitoring on the server side.
Notably, the appropriate load or error events will occur after the specified module is fetched, and
will not wait for any dependencies.
A user agent must not delay the load event for this link type.
The appropriate times to fetch and process the linked resource for such a link are:
When the external resource link is created on a link element
that is already browsing-context connected.
When the external resource link's link element becomes
browsing-context connected.
When the href attribute of the link
element of an external resource link that is already browsing-context
connected is changed.
Unlike some other link relations, changing the relevant attributes (such as as, crossorigin, and
referrerpolicy) of such a link
does not trigger a new fetch. This is because the document's module map has already been populated by a previous
fetch, and so re-fetching would be pointless.
The fetch and process the linked resource algorithm for modulepreload links, given a link element
el, is as follows:
If el's href attribute's value is the
empty string, then return.
Let destination be the current state of el's as attribute (a destination), or "script" if
it is in no state.
If destination is not script-like, then queue an element
task on the networking task source given el to fire an event named error
at el, and return.
Let url be the result of encoding-parsing a URL given
el's href attribute's value, relative to
el's node document.
If url is failure, then return.
Let settings object be el's node document's relevant settings object.
Let credentials mode be the CORS settings attribute credentials
mode for el's crossorigin
attribute.
Let cryptographic nonce be el.[[CryptographicNonce]].
Let integrity metadata be the value of el's integrity attribute, if it is specified, or the empty string
otherwise.
If el does not have an integrity
attribute, then set integrity metadata to the result of resolving a module
integrity metadata with url and settings object.
Let referrer policy be the current state of el's referrerpolicy attribute.
Let fetch priority be the current state of el's fetchpriority attribute.
Let options be a script fetch options whose cryptographic nonce is cryptographic
nonce, integrity metadata is
integrity metadata, parser
metadata is "not-parser-inserted", credentials mode is credentials
mode, referrer
policy is referrer policy, and fetch priority is
fetch priority.
Fetch a modulepreload module script graph given url, destination, settings object, options, and with the following steps given result:
If result is null, then fire an
event named error at el,
and return.
Fire an event named load at el.
The process a link header steps for this type of linked resource are to do nothing.
The following snippet shows the top part of an application with several modules preloaded:
<!DOCTYPE html>
< html lang = "en" >
< title > IRCFog</ title >
< link rel = "modulepreload" href = "app.mjs" >
< link rel = "modulepreload" href = "helpers.mjs" >
< link rel = "modulepreload" href = "irc.mjs" >
< link rel = "modulepreload" href = "fog-machine.mjs" >
< script type = "module" src = "app.mjs" >
... Assume that the module graph for the application is as follows:
Here we see the application developer has used modulepreload to declare all of the modules in their module graph,
ensuring that the user agent initiates fetches for them all. Without such preloading, the user
agent might need to go through multiple network roundtrips before discovering helpers.mjs, if technologies such as HTTP/2 Server Push are not in play. In
this way, modulepreload link elements can be
used as a sort of "manifest" of the application's modules.
The following code shows how modulepreload links can
be used in conjunction with import() to ensure network fetching is done ahead of
time, so that when import() is called, the module is already ready (but not
evaluated) in the module map:
< link rel = "modulepreload" href = "awesome-viewer.mjs" >
< button onclick = "import('./awesome-viewer.mjs').then(m => m.view())" >
View awesome thing
</ button > nofollow"The nofollow keyword may be used with a,
area, and form elements. This keyword does not create a
hyperlink, but annotates any other
hyperlinks created by the element (the implied hyperlink, if no other keywords create one).
The nofollow keyword indicates that the link is not endorsed
by the original author or publisher of the page, or that the link to the referenced document was
included primarily because of a commercial relationship between people affiliated with the two
pages.
noopener"Support in all current engines.
Support in all current engines.
The noopener keyword may be used with a,
area, and form elements. This keyword does not create a
hyperlink, but annotates any other
hyperlinks created by the element (the implied hyperlink, if no other keywords create one).
The keyword indicates that any newly created top-level traversable which results
from following the hyperlink will not contain an auxiliary browsing
context. E.g., the resulting Window's opener
getter will return null.
See also the processing model.
This typically creates a top-level traversable with an auxiliary browsing
context (assuming there is no existing navigable whose target name is "example"):
< a href = help.html target = example > Help!</ a > This creates a top-level traversable with a non-auxiliary browsing context (assuming the same thing):
< a href = help.html target = example rel = noopener > Help!</ a > These are equivalent and only navigate the parent navigable:
< a href = index.html target = _parent > Home</ a > < a href = index.html target = _parent rel = noopener > Home</ a > noreferrer"Support in all current engines.
Support in all current engines.
The noreferrer keyword may be used with a,
area, and form elements. This keyword does not create a
hyperlink, but annotates any other
hyperlinks created by the element (the implied hyperlink, if no other keywords create one).
It indicates that no referrer information is to be leaked when following the link and also
implies the noopener keyword behavior under the same
conditions.
See also the processing model where referrer is directly manipulated.
<a href="..." rel="noreferrer" target="_blank">
has the same behavior as <a href="..." rel="noreferrer noopener" target="_blank">.
opener"The opener keyword may be used with a,
area, and form elements. This keyword does not create a
hyperlink, but annotates any other
hyperlinks created by the element (the implied hyperlink, if no other keywords create one).
The keyword indicates that any newly created top-level traversable which results from following the hyperlink will contain an auxiliary browsing context.
See also the processing model.
In the following example the opener is used to allow the help
page popup to navigate its opener, e.g., in case what the user is looking for can be found
elsewhere. An alternative might be to use a named target, rather than _blank, but this has the potential to clash with existing names.
< a href = "..." rel = opener target = _blank > Help!</ a > pingback"The pingback keyword may be used with link
elements. This keyword creates an external resource
link. This keyword is body-ok.
For the semantics of the pingback keyword, see
Pingback 1.0. [PINGBACK]
preconnect"Support in all current engines.
The preconnect keyword may be used with link
elements. This keyword creates an external resource
link. This keyword is body-ok.
The preconnect keyword indicates that preemptively
initiating a connection to the origin of the specified resource is likely to be
beneficial, as it is highly likely that the user will require resources located at that
origin, and the user experience would be improved by preempting the latency costs
associated with establishing the connection.
There is no default type for resources given by the preconnect keyword.
A user agent must not delay the load event for this link type.
The appropriate times to fetch and process this type of link are:
When the external resource link is created on a link element
that is already browsing-context connected.
When the external resource link's link element becomes
browsing-context connected.
When the href attribute of the link
element of an external resource link that is already browsing-context
connected is changed.
When the crossorigin attribute of the
link element of an external resource
link that is already browsing-context connected is set, changed, or
removed.
The fetch and process the linked resource steps for this type of linked resource,
given a link element el, are to create link options from el and
to preconnect given the result.
The process a link header step for this type of linked resource given a link processing options options are to preconnect given options.
To preconnect given a link processing options options:
If options's href is an empty string, return.
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.
If url's scheme is not an HTTP(S) scheme, then return.
Let partitionKey be the result of determining the network partition key given options's environment.
Let useCredentials be true.
If options's crossorigin is Anonymous and options's origin does not have the same origin as url's origin, then set useCredentials to false.
The user agent should obtain a connection given partitionKey, url's origin, and useCredentials.
This connection is obtained but not used directly. It will remain in the connection pool for subsequent use.
The user agent should attempt to initiate a preconnect and perform the full connection handshake (DNS+TCP for HTTP, and DNS+TCP+TLS for HTTPS origins) whenever possible, but is allowed to elect to perform a partial handshake (DNS only for HTTP, and DNS or DNS+TCP for HTTPS origins), or skip it entirely, due to resource constraints or other reasons.
The optimal number of connections per origin is dependent on the negotiated protocol, users current connectivity profile, available device resources, global connection limits, and other context specific variables. As a result, the decision for how many connections should be opened is deferred to the user agent.
prefetch"The prefetch keyword may be used with link
elements. This keyword creates an external resource
link. This keyword is body-ok.
The prefetch keyword indicates that preemptively fetching and caching the specified resource or same-site document is
likely to be beneficial, as it is highly likely that the user will require this resource for
future navigations.
There is no default type for resources given by the prefetch
keyword.
The appropriate times to fetch and process this type of link are:
When the external resource link is created on a link element
that is already browsing-context connected.
When the external resource link's link element becomes
browsing-context connected.
When the href attribute of the link
element of an external resource link that is already browsing-context
connected is changed.
When the crossorigin attribute of the
link element of an external resource
link that is already browsing-context connected is set, changed, or
removed.
The fetch and process the linked resource algorithm for prefetch links, given a link element
el, is as follows:
If el's href attribute's value is the
empty string, then return.
Let options be the result of creating link options from el.
Set options's destination to the empty string.
Let request be the result of creating a link request given options.
If request is null, then return.
Set request's initiator to
"prefetch".
Let processPrefetchResponse be the following steps given a response response and null, failure, or a byte sequence bytesOrNull:
If response is a network error, fire an event named error at el.
Otherwise, fire an event named load at el.
The user agent should fetch request, with processResponseConsumeBody set to processPrefetchResponse. User agents may delay the fetching of request to prioritize other requests that are necessary for the current document.
The process a link header steps for this type of linked resource are to do nothing.
preload"Support in one engine only.
The preload keyword may be used with link
elements. This keyword creates an external resource
link. This keyword is body-ok.
The preload keyword indicates that the user agent will
preemptively fetch and cache the specified resource according
to the potential destination given by the
as attribute, and the priority given by the fetchpriority attribute, as it is highly likely that the
user will require this resource for the current navigation.
User-agents might perform additional operations when a resource is loaded, such as preemptively decoding images or creating stylesheets. However, these additional operations cannot have observable effects.
There is no default type for resources given by the preload
keyword.
A user agent must not delay the load event for this link type.
The appropriate times to fetch and process the linked resource for such a link are:
When the external resource link is created on a link element
that is already browsing-context connected.
When the external resource link's link element becomes
browsing-context connected.
When the href attribute of the link
element of an external resource link that is already browsing-context
connected is changed.
When the as attribute of the link
element of an external resource link that is already browsing-context
connected is changed.
When the type attribute of the link
element of an external resource link that is already browsing-context
connected, but was previously not obtained due to the type attribute specifying an unsupported type for the request
destination, is set, removed, or
changed.
When the media attribute of the link
element of an external resource link that is already browsing-context
connected, but was previously not obtained due to the media attribute not
matching the environment, is changed or
removed.
A Document has a map of preloaded resources, which is an
ordered map, initially empty.
A preload key is a struct. It has the following items:
same-origin", "cors", or
"no-cors"
A preload entry is a struct. It has the following items:
To consume a preloaded resource for Window window,
given a URL url, a string destination, a string
mode, a string credentialsMode, a string integrityMetadata, and
onResponseAvailable, which is an algorithm accepting a response:
Let key be a preload key whose URL is url, destination is destination, mode is mode, and credentials mode is credentialsMode.
Let preloads be window's associated Document's map of
preloaded resources.
If key does not exist in preloads, then return false.
Let entry be preloads[key].
Let consumerIntegrityMetadata be the result of parsing integrityMetadata.
Let preloadIntegrityMetadata be the result of parsing entry's integrity metadata.
If none of the following conditions apply:
consumerIntegrityMetadata is no metadata;
consumerIntegrityMetadata is equal to preloadIntegrityMetadata; or
This comparison would ignore unknown integrity options. See issue #116.
then return false.
A mismatch in integrity metadata between the preload and the consumer, even if both match the data, would lead to an additional fetch from the network.
It is important that network errors are added to the preload cache so that if a preload request results in an error, the erroneous response isn't re-requested from the network later. This also has security implications; consider the case where a developer specifies subresource integrity metadata on a preload request, but not the following resource request. If the preload request fails subresource integrity verification and is discarded, the resource request will fetch and consume a potentially-malicious response from the network without verifying its integrity. [SRI]
Remove preloads[key].
If entry's response is null, then set entry's on response available to onResponseAvailable.
Otherwise, call onResponseAvailable with entry's response.
Return true.
For the purposes of this section, a string type matches a string destination if the following algorithm returns true:
If type is an empty string, then return true.
If destination is "fetch", then return true.
Let mimeTypeRecord be the result of parsing type.
If mimeTypeRecord is failure, then return false.
If mimeTypeRecord is not supported by the user agent, then return false.
If any of the following are true:
destination is "audio" or "video", and mimeTypeRecord is an
audio or video MIME type;
destination is a script-like destination and mimeTypeRecord is a JavaScript MIME type;
destination is "image" and
mimeTypeRecord is an image MIME type;
destination is "font" and
mimeTypeRecord is a font MIME type;
destination is "json" and
mimeTypeRecord is a JSON MIME type;
destination is "style" and
mimeTypeRecord's essence is
text/css; or
destination is "track" and
mimeTypeRecord's essence is
text/vtt,
then return true.
Return false.
To create a preload key for a request request, return a new preload key whose URL is request's URL, destination is request's destination, mode is request's mode, and credentials mode is request's credentials mode.
To translate a preload destination given a string destination:
If destination is not "fetch", "font",
"image", "script", "style",
or "track", then return null.
Return the result of translating destination.
To preload given a link processing options options and an optional processResponse, which is an algorithm accepting a response:
If options's type doesn't match options's destination, then return.
If options's destination is
"image" and options's source set is not null, then set options's href to the result of selecting an image source from options's source set.
Let request be the result of creating a link request given options.
If request is null, then return.
Let unsafeEndTime be 0.
Let entry be a new preload entry whose integrity metadata is options's integrity.
Let key be the result of creating a preload key given request.
If options's document is null, then
set request's initiator type to
"early hint".
Let controller be null.
Let reportTiming given a Document document be to
report timing for controller given document's relevant
global object.
Set controller to the result of fetching request, with processResponseConsumeBody set to the following steps given a response response and null, failure, or a byte sequence bodyBytes:
If bodyBytes is a byte sequence, then set response's body to bodyBytes as a body.
By using processResponseConsumeBody, we have extracted the entire body. This is necessary to ensure the preloader loads the entire body from the network, regardless of whether the preload will be consumed (which is uncertain at this point). This step then resets the request's body to a new body containing the same bytes, so that other specifications can read from it at the time of actual consumption, despite us having already done so once.
Otherwise, set response to a network error.
Set unsafeEndTime to the unsafe shared current time.
If options's document is not null, then call reportTiming given options's document.
If entry's on response available is null, then set entry's response to response; otherwise call entry's on response available given response.
If processResponse is given, then call processResponse with response.
Let commit be the following steps given a Document
document:
If entry's response is not null, then call reportTiming given document.
Set document's map of preloaded resources[key] to entry.
If options's document is null, then set options's on document ready to commit. Otherwise, call commit with options's document.
The fetch and process the linked resource steps for this type of linked resource,
given a link element el, are:
Update the source set for el.
Let options be the result of creating link options from el.
Preload options, with the following steps given a response response:
If response is a network error, fire an event named error at el. Otherwise, fire an event named
load at el.
The actual browsers' behavior is different from the spec here, and the feasibility of changing the behavior has not yet been investigated. See issue #1142.
The process a link header step for this type of link given a link processing options options is to preload options.
privacy-policy"The privacy-policy keyword may be used with
link, a, and area elements. This keyword creates a
hyperlink.
The privacy-policy keyword indicates that the
referenced document contains information about the data collection and usage practices that apply
to the current document, as described in more detail in Additional Link Relation
Types. The referenced document may be a standalone privacy policy, or a specific section of
some more general document. [RFC6903]
search"The search keyword may be used with link,
a, area, and form elements. This keyword creates a
hyperlink.
The search keyword indicates that the referenced document
provides an interface specifically for searching the document and its related resources.
OpenSearch description documents can be used with link elements and
the search link type to enable user agents to autodiscover search
interfaces. [OPENSEARCH]
stylesheet"The stylesheet keyword may be used with link
elements. This keyword creates an external resource
link that contributes to the styling processing model. This keyword is
body-ok.
The specified resource is a CSS style sheet that describes how to present the document.
Support in one engine only.
If the alternate keyword is also specified on the
link element, then the link is an
alternative style sheet; in this case, the title attribute
must be specified on the link element, with a non-empty value.
The default type for resources given by the stylesheet
keyword is text/css.
A link element of this type is implicitly potentially render-blocking
if the element was created by its node document's parser.
When the disabled attribute of a link
element with a stylesheet keyword is set, disable the associated CSS style sheet.
The appropriate times to fetch and process this type of link are:
When the external resource link is created on a link element
that is already browsing-context connected.
When the external resource link's link element becomes
browsing-context connected.
When the href attribute of the link
element of an external resource link that is already browsing-context
connected is changed.
When the disabled attribute of the
link element of an external resource link that is already
browsing-context connected is set, changed, or removed.
When the crossorigin attribute of the
link element of an external resource
link that is already browsing-context connected is set, changed, or
removed.
When the type attribute of the link
element of an external resource link that is already browsing-context
connected is set or changed to a value that does not or no longer matches the Content-Type metadata of the previous obtained external resource, if
any.
When the type attribute of the link
element of an external resource link that is already browsing-context
connected, but was previously not obtained due to the type attribute specifying an unsupported type, is removed or
changed.
When the external resource link that is already browsing-context connected changes from being an alternative style sheet to not being one, or vice versa.
Quirk: If the document has been set to quirks mode, has the
same origin as the URL of the external resource,
and the Content-Type metadata of the external resource is not a
supported style sheet type, the user agent must instead assume it to be text/css.
The linked resource fetch setup steps for this type of linked resource, given a
link element el and request
request, are:
If el's disabled attribute is set,
then return false.
If el contributes a script-blocking style sheet, append el to its node document's script-blocking style sheet set.
If el's media attribute's value
matches the environment and el is
potentially render-blocking, then block rendering on
el.
If el is currently render-blocking, then set request's render-blocking to true.
Return true.
See issue #968 for plans
to use the CSSOM fetch a CSS
style sheet algorithm instead of the default fetch and process the linked
resource algorithm. In the meantime, any critical
subresource request should have its render-blocking set to whether or not the
link element is currently render-blocking.
To process this type of linked resource
given a link element el, boolean success, response response, and byte sequence
bodyBytes:
If the resource's Content-Type metadata is not
text/css, then set success to false.
If el no longer creates an external resource link that contributes to the styling processing model, or if, since the resource in question was fetched, it has become appropriate to fetch it again, then:
Remove el from el's node document's script-blocking style sheet set.
Return.
If el has an associated CSS style sheet, remove the CSS style sheet.
If success is true, then:
Create a CSS style sheet with the following properties:
response's URL list[0]
We provide a URL here on the assumption that w3c/csswg-drafts issue #9316 will be fixed.
el
The media attribute of el.
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 el, if
el is in a document tree, or the empty string otherwise.
This is similarly a reference to the attribute, rather than a copy of the attribute's current value.
Set if the link is an alternative style sheet and el's explicitly enabled is false; unset otherwise.
Set if the resource is CORS-same-origin; unset otherwise.
null
Left at its default value.
Left uninitialized.
This doesn't seem right. Presumably we should be using bodyBytes? Tracked as issue #2997.
The CSS environment encoding is the result of running the following steps: [CSSSYNTAX]
If el has a charset attribute,
get an encoding from that attribute's value. If
that succeeds, return the resulting encoding. [ENCODING]
Otherwise, return the document's character encoding. [DOM]
Fire an event named load at el.
Otherwise, fire an event named error at el.
If el contributes a script-blocking style sheet, then:
Assert: el's node document's script-blocking style sheet set contains el.
Remove el from its node document's script-blocking style sheet set.
Unblock rendering on el.
The process a link header steps for this type of linked resource are to do nothing.
tag"The tag keyword may be used with a and
area elements. This keyword creates a hyperlink.
The tag keyword indicates that the tag that the
referenced document represents applies to the current document.
Since it indicates that the tag applies to the current document, it would be inappropriate to use this keyword in the markup of a tag cloud, which lists the popular tags across a set of pages.
This document is about some gems, and so it is tagged with "https://en.wikipedia.org/wiki/Gemstone" to unambiguously categorize it as applying
to the "jewel" kind of gems, and not to, say, the towns in the US, the Ruby package format, or
the Swiss locomotive class:
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< title > My Precious</ title >
</ head >
< body >
< header >< h1 > My precious</ h1 > < p > Summer 2012</ p ></ header >
< p > Recently I managed to dispose of a red gem that had been
bothering me. I now have a much nicer blue sapphire.</ p >
< p > The red gem had been found in a bauxite stone while I was digging
out the office level, but nobody was willing to haul it away. The
same red gem stayed there for literally years.</ p >
< footer >
Tags: < a rel = tag href = "https://en.wikipedia.org/wiki/Gemstone" > Gemstone</ a >
</ footer >
</ body >
</ html > In this document, there are two articles. The "tag"
link, however, applies to the whole page (and would do so wherever it was placed, including if it
was within the article elements).
<!DOCTYPE HTML>
< html lang = "en" >
< head >
< title > Gem 4/4</ title >
</ head >
< body >
< article >
< h1 > 801: Steinbock</ h1 >
< p > The number 801 Gem 4/4 electro-diesel has an ibex and was rebuilt in 2002.</ p >
</ article >
< article >
< h1 > 802: Murmeltier</ h1 >
< figure >
< img src = "https://upload.wikimedia.org/wikipedia/commons/b/b0/Trains_de_la_Bernina_en_hiver_2.jpg"
alt = "The 802 was red with pantographs and tall vents on the side." >
< figcaption > The 802 in the 1980s, above Lago Bianco.</ figcaption >
</ figure >
< p > The number 802 Gem 4/4 electro-diesel has a marmot and was rebuilt in 2003.</ p >
</ article >
< p class = "topic" >< a rel = tag href = "https://en.wikipedia.org/wiki/Rhaetian_Railway_Gem_4/4" > Gem 4/4</ a ></ p >
</ body >
</ html > terms-of-service"The terms-of-service keyword may be used with
link, a, and area elements. This keyword creates a
hyperlink.
The terms-of-service keyword indicates that the
referenced document contains information about the agreements between the current document's
provider and users who wish to use the current document, as described in more detail in
Additional Link Relation Types. [RFC6903]
Some documents form part of a sequence of documents.
A sequence of documents is one where each document can have a previous sibling and a next sibling. A document with no previous sibling is the start of its sequence, a document with no next sibling is the end of its sequence.
A document may be part of multiple sequences.
next"The next keyword may be used with link,
a, area, and form elements. This keyword creates a
hyperlink.
The next keyword indicates that the document is part of a
sequence, and that the link is leading to the document that is the next logical document in the
sequence.
When the next keyword is used with a link
element, user agents should process such links as if they were using one of the dns-prefetch, preconnect, or
prefetch keywords. Which keyword the user agent wishes to use
is implementation-dependent; for example, a user agent may wish to use the less-costly preconnect processing model when trying to conserve data, battery
power, or processing power, or may wish to pick a keyword depending on heuristic analysis of past
user behavior in similar scenarios.
prev"The prev keyword may be used with link,
a, area, and form elements. This keyword creates a
hyperlink.
The prev keyword indicates that the document is part of a
sequence, and that the link is leading to the document that is the previous logical document in
the sequence.
Synonyms: For historical reasons, user agents must also treat the keyword
"previous" like the prev keyword.
Extensions to the predefined set of link types may be registered on the microformats page for existing rel values. [MFREL]
Anyone is free to edit the microformats page for existing rel values at any time to add a type. Extension types must be specified with the following information:
The actual value being defined. The value should not be confusingly similar to any other defined value (e.g. differing only in case).
If the value contains a U+003A COLON character (:), it must also be an absolute URL.
linkOne of the following:
link elements.link element; it creates a
hyperlink.link element; it creates an external
resource link.a and areaOne of the following:
a and area elements.a and area elements; it creates a
hyperlink.a and area elements; it creates
an external resource link.a and area elements; it annotates other hyperlinks
created by the element.formOne of the following:
form elements.form elements; it creates a
hyperlink.form elements; it creates an external
resource link.form elements; it annotates other hyperlinks created by the
element.A short non-normative description of what the keyword's meaning is.
A link to a more detailed description of the keyword's semantics and requirements. It could be another page on the wiki, or a link to an external page.
A list of other keyword values that have exactly the same processing requirements. Authors should not use the values defined to be synonyms, they are only intended to allow user agents to support legacy content. Anyone may remove synonyms that are not used in practice; only names that need to be processed as synonyms for compatibility with legacy content are to be registered in this way.
One of the following:
If a keyword is found to be redundant with existing values, it should be removed and listed as a synonym for the existing value.
If a keyword is registered in the "proposed" state for a period of a month or more without being used or specified, then it may be removed from the registry.
If a keyword is added with the "proposed" status and found to be redundant with existing values, it should be removed and listed as a synonym for the existing value. If a keyword is added with the "proposed" status and found to be harmful, then it should be changed to "discontinued" status.
Anyone can change the status at any time, but should only do so in accordance with the definitions above.
Conformance checkers must use the information given on the microformats page for existing rel values to establish if a value is allowed or not: values defined in this specification or marked as "proposed" or "ratified" must be accepted when used on the elements for which they apply as described in the "Effect on..." field, whereas values marked as "discontinued" or not listed in either this specification or on the aforementioned page must be rejected as invalid. Conformance checkers may cache this information (e.g. for performance reasons or to avoid the use of unreliable network connectivity).
When an author uses a new type not defined by either this specification or the wiki page, conformance checkers should offer to add the value to the wiki, with the details described above, with the "proposed" status.
Types defined as extensions in the microformats
page for existing rel values with the status "proposed" or "ratified" may be used with the
rel attribute on link, a, and area
elements in accordance to the "Effect on..." field. [MFREL]
The ins and del elements represent edits to the document.
ins elementSupport in all current engines.
cite — Link to the source of the quotation or more information about the edit
datetime — Date and (optionally) time of the change
HTMLModElement.The ins element represents an addition to the document.
The following represents the addition of a single paragraph:
< aside >
< ins >
< p > I like fruit. </ p >
</ ins >
</ aside > As does the following, because everything in the aside element here counts as
phrasing content and therefore there is just one paragraph:
< aside >
< ins >
Apples are < em > tasty</ em > .
</ ins >
< ins >
So are pears.
</ ins >
</ aside > ins elements should not cross implied paragraph
boundaries.
The following example represents the addition of two paragraphs, the second of which was
inserted in two parts. The first ins element in this example thus crosses a
paragraph boundary, which is considered poor form.
< aside >
<!-- don't do this -->
< ins datetime = "2005-03-16 00:00Z" >
< p > I like fruit. </ p >
Apples are < em > tasty</ em > .
</ ins >
< ins datetime = "2007-12-19 00:00Z" >
So are pears.
</ ins >
</ aside > Here is a better way of marking this up. It uses more elements, but none of the elements cross implied paragraph boundaries.
< aside >
< ins datetime = "2005-03-16 00:00Z" >
< p > I like fruit. </ p >
</ ins >
< ins datetime = "2005-03-16 00:00Z" >
Apples are < em > tasty</ em > .
</ ins >
< ins datetime = "2007-12-19 00:00Z" >
So are pears.
</ ins >
</ aside > del elementSupport in all current engines.
cite — Link to the source of the quotation or more information about the edit
datetime — Date and (optionally) time of the change
HTMLModElement.The del element represents a removal from the document.
del elements should not cross implied paragraph
boundaries.
The following shows a "to do" list where items that have been done are crossed-off with the date and time of their completion.
< h1 > To Do</ h1 >
< ul >
< li > Empty the dishwasher</ li >
< li >< del datetime = "2009-10-11T01:25-07:00" > Watch Walter Lewin's lectures</ del ></ li >
< li >< del datetime = "2009-10-10T23:38-07:00" > Download more tracks</ del ></ li >
< li > Buy a printer</ li >
</ ul > ins and del elementsThe cite attribute
may be used to specify the URL of a document that
explains the change. When that document is long, for instance the minutes of a meeting, authors
are encouraged to include a fragment pointing to the
specific part of that document that discusses the change.
If the cite attribute is present, it must be a valid
URL potentially surrounded by spaces that explains the change. 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 edits), not for readers.
The datetime
attribute may be used to specify the time and date of the change.
If present, the datetime attribute's value must be a
valid date string with optional time.
User agents must parse the datetime attribute according
to the parse a date or time string algorithm. If that doesn't return a date or a global date and time,
then the modification has no associated timestamp (the value is non-conforming; it is not a
valid date string with optional time). Otherwise, the modification is marked as
having been made at the given date or global date and time. If the given value is a global date and time, then user agents should use the associated
time-zone offset information to determine which time zone to present the given datetime in.
This value may be shown to the user, but it is primarily intended for private use.
The ins and del elements must implement the
HTMLModElement interface:
Support in all current engines.
[Exposed =Window ]
interface HTMLModElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions , ReflectURL ] attribute USVString cite ;
[CEReactions , Reflect ] attribute DOMString dateTime ;
};This section is non-normative.
Since the ins and del elements do not affect paragraphing, it is possible, in some cases where paragraphs are implied (without explicit p elements), for an
ins or del element to span both an entire paragraph or other
non-phrasing content elements and part of another paragraph. For example:
< section >
< ins >
< p >
This is a paragraph that was inserted.
</ p >
This is another paragraph whose first sentence was inserted
at the same time as the paragraph above.
</ ins >
This is a second sentence, which was there all along.
</ section > By only wrapping some paragraphs in p elements, one can even get the end of one
paragraph, a whole second paragraph, and the start of a third paragraph to be covered by the same
ins or del element (though this is very confusing, and not considered
good practice):
< section >
This is the first paragraph. < ins > This sentence was
inserted.
< p > This second paragraph was inserted.</ p >
This sentence was inserted too.</ ins > This is the
third paragraph in this example.
<!-- (don't do this) -->
</ section > However, due to the way implied paragraphs are defined, it is
not possible to mark up the end of one paragraph and the start of the very next one using the same
ins or del element. You instead have to use one (or two) p
element(s) and two ins or del elements, as for example:
< section >
< p > This is the first paragraph. < del > This sentence was
deleted.</ del ></ p >
< p >< del > This sentence was deleted too.</ del > That
sentence needed a separate < del> element.</ p >
</ section > Partly because of the confusion described above, authors are strongly encouraged to always mark
up all paragraphs with the p element, instead of having ins or
del elements that cross implied paragraphs
boundaries.
This section is non-normative.
The content models of the ol and ul elements do not allow
ins and del elements as children. Lists always represent all their
items, including items that would otherwise have been marked as deleted.
To indicate that an item is inserted or deleted, an ins or del
element can be wrapped around the contents of the li element. To indicate that an
item has been replaced by another, a single li element can have one or more
del elements followed by one or more ins elements.
In the following example, a list that started empty had items added and removed from it over time. The bits in the example that have been emphasized show the parts that are the "current" state of the list. The list item numbers don't take into account the edits, though.
< h1 > Stop-ship bugs</ h1 >
< ol >
< li >< ins datetime = "2008-02-12T15:20Z" > Bug 225:
Rain detector doesn't work in snow</ ins ></ li >
< li >< del datetime = "2008-03-01T20:22Z" >< ins datetime = "2008-02-14T12:02Z" > Bug 228:
Water buffer overflows in April</ ins ></ del ></ li >
< li >< ins datetime = "2008-02-16T13:50Z" > Bug 230:
Water heater doesn't use renewable fuels</ ins ></ li >
< li >< del datetime = "2008-02-20T21:15Z" >< ins datetime = "2008-02-16T14:25Z" > Bug 232:
Carbon dioxide emissions detected after startup</ ins ></ del ></ li >
</ ol > In the following example, a list that started with just fruit was replaced by a list with just colors.
< h1 > List of < del > fruits</ del >< ins > colors</ ins ></ h1 >
< ul >
< li >< del > Lime</ del >< ins > Green</ ins ></ li >
< li >< del > Apple</ del ></ li >
< li > Orange</ li >
< li >< del > Pear</ del ></ li >
< li >< ins > Teal</ ins ></ li >
< li >< del > Lemon</ del >< ins > Yellow</ ins ></ li >
< li > Olive</ li >
< li >< ins > Purple</ ins ></ li >
</ ul > This section is non-normative.
The elements that form part of the table model have complicated content model requirements that
do not allow for the ins and del elements, so indicating edits to a
table can be difficult.
To indicate that an entire row or an entire column has been added or removed, the entire
contents of each cell in that row or column can be wrapped in ins or del
elements (respectively).
Here, a table's row has been added:
< table >
< thead >
< tr > < th > Game name < th > Game publisher < th > Verdict
< tbody >
< tr > < td > Diablo 2 < td > Blizzard < td > 8/10
< tr > < td > Portal < td > Valve < td > 10/10
< tr > < td > < ins > Portal 2</ ins > < td > < ins > Valve</ ins > < td > < ins > 10/10</ ins >
</ table > Here, a column has been removed (the time at which it was removed is given also, as is a link to the page explaining why):
< table >
< thead >
< tr > < th > Game name < th > Game publisher < th > < del cite = "/edits/r192" datetime = "2011-05-02 14:23Z" > Verdict</ del >
< tbody >
< tr > < td > Diablo 2 < td > Blizzard < td > < del cite = "/edits/r192" datetime = "2011-05-02 14:23Z" > 8/10</ del >
< tr > < td > Portal < td > Valve < td > < del cite = "/edits/r192" datetime = "2011-05-02 14:23Z" > 10/10</ del >
< tr > < td > Portal 2 < td > Valve < td > < del cite = "/edits/r192" datetime = "2011-05-02 14:23Z" > 10/10</ del >
</ table > Generally speaking, there is no good way to indicate more complicated edits (e.g. that a cell was removed, moving all subsequent cells up or to the left).
picture elementSupport in all current engines.
Support in all current engines.
source elements, followed by one img element,
optionally intermixed with script-supporting elements.[Exposed =Window ]
interface HTMLPictureElement : HTMLElement {
[HTMLConstructor ] constructor ();
};The picture element is a container
which provides multiple sources to its contained img element
to allow authors to declaratively control or give hints to the user agent about which image resource to use,
based on the screen pixel density, viewport size, image format, and other factors.
It represents its children.
The picture element is somewhat different from the similar-looking
video and audio elements. While all of them contain source
elements, the source element's src attribute
has no meaning when the element is nested within a picture element, and the resource
selection algorithm is different. Also, the picture element itself does not display
anything; it merely provides a context for its contained img element that enables it
to choose from multiple URLs.
source elementSupport in all current engines.
Support in all current engines.
picture element, before the img element.track elements.type — Type of embedded resource
media — Applicable media
src (in audio or video) — Address of the resource
srcset (in picture) — Images to use in different situations, e.g., high-resolution displays, small monitors, etc.
sizes (in picture) — Image sizes for different page layouts
width (in picture) — Horizontal dimension
height (in picture) — Vertical dimension
[Exposed =Window ]
interface HTMLSourceElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions , ReflectURL ] attribute USVString src ;
[CEReactions , Reflect ] attribute DOMString type ;
[CEReactions , Reflect ] attribute USVString srcset ;
[CEReactions , Reflect ] attribute DOMString sizes ;
[CEReactions , Reflect ] attribute DOMString media ;
[CEReactions , Reflect ] attribute unsigned long width ;
[CEReactions , Reflect ] attribute unsigned long height ;
};The source element allows authors to specify multiple alternative
source sets for img elements or multiple alternative
media resources for media
elements. It does not represent anything on its own.
The type attribute
may be present. If present, the value must be a valid MIME type string.
The media
attribute may also be present. If present, the value must contain a valid media query
list. The user agent will skip to the next source element if the value does
not match the environment.
The media attribute is only evaluated
once during the resource selection algorithm
for media elements. In contrast, when using the
picture element, the user agent will react to
changes in the environment.
The remainder of the requirements depend on whether the parent is a picture
element or a media element:
source element's parent is a picture elementThe srcset
attribute must be present, and is a srcset attribute.
The srcset attribute contributes the image sources to the source set, if the
source element is selected.
If the srcset attribute has any image candidate strings using a width descriptor, the
sizes attribute may also be present. If, additionally,
the following sibling img element does not allow
auto-sizes, the sizes attribute must be present.
The sizes
attribute is a sizes attribute, which contributes the source size to
the source set, if the source element is selected.
If the img element allows auto-sizes, then the sizes attribute can be omitted on previous sibling
source elements. In such cases, it is equivalent to specifying auto.
The source element supports dimension attributes. The
img element can use the width and height attributes of a source element, instead of
those on the img element itself, to determine its rendered dimensions and
aspect-ratio, as defined in the Rendering section.
The type attribute gives the type of the images in the
source set, to allow the user agent to skip to the next source element
if it does not support the given type.
If the type attribute is not
specified, the user agent will not select a different source element if it finds
that it does not support the image format after fetching it.
When a source element has a following sibling source element or
img element with a srcset attribute
specified, it must have at least one of the following:
A media attribute specified with a value that,
after stripping leading and trailing
ASCII whitespace, is not the empty string and is not an ASCII
case-insensitive match for the string "all".
A type attribute specified.
The src attribute must not be present.
source element's parent is a media elementThe src attribute
gives the URL of the media resource. The value must be a valid
non-empty URL potentially surrounded by spaces. This attribute must be present.
The type attribute gives the type of the media
resource, to help the user agent determine if it can play this media
resource before fetching it. The codecs parameter, which certain
MIME types define, might be necessary to specify exactly how the resource is encoded.
[RFC6381]
Dynamically modifying a source element's src or type attribute
when the element is already inserted in a video or audio element will
have no effect. To change what is playing, just use the src
attribute on the media element directly, possibly making use of the canPlayType() method to pick from amongst available
resources. Generally, manipulating source elements manually after the document has
been parsed is an unnecessarily complicated approach.
The following list shows some examples of how to use the codecs= MIME
parameter in the type attribute.
< source src = 'video.mp4' type = 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"' > < source src = 'video.mp4' type = 'video/mp4; codecs="avc1.58A01E, mp4a.40.2"' > < source src = 'video.mp4' type = 'video/mp4; codecs="avc1.4D401E, mp4a.40.2"' > < source src = 'video.mp4' type = 'video/mp4; codecs="avc1.64001E, mp4a.40.2"' > < source src = 'video.mp4' type = 'video/mp4; codecs="mp4v.20.8, mp4a.40.2"' > < source src = 'video.mp4' type = 'video/mp4; codecs="mp4v.20.240, mp4a.40.2"' > < source src = 'video.3gp' type = 'video/3gpp; codecs="mp4v.20.8, samr"' > < source src = 'video.ogv' type = 'video/ogg; codecs="theora, vorbis"' > < source src = 'video.ogv' type = 'video/ogg; codecs="theora, speex"' > < source src = 'audio.ogg' type = 'audio/ogg; codecs=vorbis' > < source src = 'audio.spx' type = 'audio/ogg; codecs=speex' > < source src = 'audio.oga' type = 'audio/ogg; codecs=flac' > < source src = 'video.ogv' type = 'video/ogg; codecs="dirac, vorbis"' > The source HTML element insertion steps, given
insertedNode, are:
Let parent be insertedNode's parent.
If parent is a media element that has no src attribute and whose networkState has the value NETWORK_EMPTY, then invoke that media
element's resource selection
algorithm.
If parent is a picture element, then for each child of parent's children, if child is an img element,
then count this as a relevant mutation for
child.
The source HTML element moving steps, given movedNode and
oldParent, are:
If oldParent is a picture element, then for each child of oldParent's children, if child is an img element,
then count this as a relevant mutation for
child.
The source HTML element removing steps, given removedNode
and oldParent, are:
If oldParent is a picture element, then for each child of oldParent's children, if child is an img element,
then count this as a relevant mutation for
child.
If the author isn't sure if user agents will all be able to render the media resources
provided, the author can listen to the error event on the last
source element and trigger fallback behavior:
< script >
function fallback( video) {
// replace <video> with its contents
while ( video. hasChildNodes()) {
if ( video. firstChild instanceof HTMLSourceElement)
video. removeChild( video. firstChild);
else
video. parentNode. insertBefore( video. firstChild, video);
}
video. parentNode. removeChild( video);
}
</ script >
< video controls autoplay >
< source src = 'video.mp4' type = 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"' >
< source src = 'video.ogv' type = 'video/ogg; codecs="theora, vorbis"'
onerror = "fallback(parentNode)" >
...
</ video > img 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.
Support in all current engines.
Support in all current engines.
usemap attribute: Interactive content.picture element, after all source elements.alt — Replacement text for use when images are not available
src — Address of the resource
srcset — Images to use in different situations, e.g., high-resolution displays, small monitors, etc.
sizes — Image sizes for different page layouts
crossorigin — How the element handles crossorigin requests
usemap — Name of image map to use
ismap — Whether the image is a server-side image map
width — Horizontal dimension
height — Vertical dimension
referrerpolicy — Referrer policy for fetches initiated by the element
decoding — Decoding hint to use when processing this image for presentation
loading — Used when determining loading deferral
fetchpriority — Sets the priority for fetches initiated by the element
alt attribute: for authors; for implementers.[Exposed =Window ,
LegacyFactoryFunction =Image (optional unsigned long width , optional unsigned long height )]
interface HTMLImageElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions , Reflect ] attribute DOMString alt ;
[CEReactions , ReflectURL ] attribute USVString src ;
[CEReactions , Reflect ] attribute USVString srcset ;
[CEReactions , Reflect ] attribute DOMString sizes ;
[CEReactions ] attribute DOMString ? crossOrigin ;
[CEReactions , Reflect ] attribute DOMString useMap ;
[CEReactions , Reflect ] attribute boolean isMap ;
[CEReactions , ReflectSetter ] attribute unsigned long width ;
[CEReactions , ReflectSetter ] attribute unsigned long height ;
readonly attribute unsigned long naturalWidth ;
readonly attribute unsigned long naturalHeight ;
readonly attribute boolean complete ;
readonly attribute USVString currentSrc ;
[CEReactions ] attribute DOMString referrerPolicy ;
[CEReactions ] attribute DOMString decoding ;
[CEReactions ] attribute DOMString loading ;
[CEReactions ] attribute DOMString fetchPriority ;
Promise <undefined > decode ();
// also has obsolete members
};An img element represents an image.
An img element has a dimension
attribute source, initially set to the element itself.
Support in all current engines.
Support in all current engines.
The image given by the src
and srcset attributes, and
any previous sibling source elements' srcset
attributes if the parent is a picture element, is the embedded content; the value of
the alt attribute provides
equivalent content for those who cannot process images or who have image loading disabled (i.e.,
it is the img element's fallback content).
The requirements on the alt attribute's value are described
in a separate section.
At least one of the src and srcset attributes must be present.
If the src attribute is present, it must contain a
valid non-empty URL potentially surrounded by spaces referencing a non-interactive,
optionally animated, image resource that is neither paged nor scripted.
The requirements above imply that images can be static bitmaps (e.g. PNGs, GIFs, JPEGs), single-page vector documents (single-page PDFs, XML files with an SVG document element), animated bitmaps (APNGs, animated GIFs), animated vector graphics (XML files with an SVG document element that use declarative SMIL animation), and so forth. However, these definitions preclude SVG files with script, multipage PDF files, interactive MNG files, HTML documents, plain text documents, and the like. [PNG] [GIF] [JPEG] [PDF] [XML] [APNG] [SVG] [MNG]
The srcset attribute is a srcset
attribute.
The srcset attribute and the src attribute (if width
descriptors are not used) contribute the image sources
to the source set (if no source element was selected).
If the srcset attribute is present and has any image candidate strings using a width
descriptor, the sizes attribute must also be present.
If the srcset attribute is not specified, and the
loading attribute is in the Lazy state, the sizes attribute may be specified with the value "auto" (ASCII case-insensitive). The sizes attribute is a sizes attribute,
which contributes the source size to the source set (if no
source element was selected).
An img element allows auto-sizes if:
loading attribute is in the Lazy state, andsizes attribute's value is "auto" (ASCII case-insensitive), or starts with "auto," (ASCII case-insensitive).Support in all current engines.
The crossorigin
attribute is a CORS settings attribute. Its purpose is to allow images from
third-party sites that allow cross-origin access to be used with canvas.
The referrerpolicy attribute is a referrer
policy attribute. Its purpose is to set the referrer policy used when fetching the image. [REFERRERPOLICY]
The decoding
attribute indicates the preferred method to decode this
image. The attribute, if present, must be an image decoding hint. This attribute's missing value default and invalid value default are both the Auto state.
HTMLImageElement/fetchPriority
The fetchpriority attribute is a fetch
priority attribute. Its purpose is to set the priority used when fetching the image.
The loading attribute is a lazy
loading attribute. Its purpose is to indicate the policy for loading images that are
outside the viewport.
When the loading attribute's state is changed to the
Eager state, the user agent must run these
steps:
Let resumptionSteps be the img element's lazy load
resumption steps.
If resumptionSteps is null, then return.
Set the img's lazy load resumption steps to null.
Invoke resumptionSteps.
< img src = "1.jpeg" alt = "1" >
< img src = "2.jpeg" loading = eager alt = "2" >
< img src = "3.jpeg" loading = lazy alt = "3" >
< div id = very-large ></ div > <!-- Everything after this div is below the viewport -->
< img src = "4.jpeg" alt = "4" >
< img src = "5.jpeg" loading = lazy alt = "5" > In the example above, the images load as follows:
1.jpeg, 2.jpeg,
4.jpegThe images load eagerly and delay the window's load event.
3.jpegThe image loads when layout is known, due to being in the viewport, however it does not delay the window's load event.
5.jpegThe image loads only once scrolled into the viewport, and does not delay the window's load event.
Developers are encouraged to specify a preferred aspect ratio via width and height attributes
on lazy loaded images, even if CSS sets the image's width and height properties, to prevent the
page layout from shifting around after the image loads.
The img HTML element insertion steps, given insertedNode,
are:
If insertedNode's parent is a picture element, then, count this as
a relevant mutation for
insertedNode.
The img HTML element moving steps, given movedNode and
oldParent, are:
If oldParent is a picture element, then, count this as a relevant mutation for movedNode.
The img HTML element removing steps, given removedNode and
oldParent, are:
If oldParent is a picture element, then, count this as a
relevant mutation for removedNode.
The img element must not be used as a layout tool. In particular, img
elements should not be used to display transparent images, as such images rarely convey meaning and
rarely add anything useful to the document.
What an img element represents depends on the src attribute and the alt
attribute.
src attribute is set and the alt attribute is set to the empty stringThe image is either decorative or supplemental to the rest of the content, redundant with some other information in the document.
If the image is available and the user agent is configured to display that image, then the element represents the element's image data.
Otherwise, the element represents nothing, and may be omitted completely from the rendering. User agents may provide the user with a notification that an image is present but has been omitted from the rendering.
src attribute is set and the alt attribute is set to a value that isn't emptyThe image is a key part of the content; the alt attribute
gives a textual equivalent or replacement for the image.
If the image is available and the user agent is configured to display that image, then the element represents the element's image data.
Otherwise, the element represents the text given by the alt attribute. User agents may provide the user with a notification
that an image is present but has been omitted from the rendering.
src attribute is set and the alt attribute is notThe image might be a key part of the content, and there is no textual equivalent of the image available.
In a conforming document, the absence of the alt attribute indicates that the image is a key part of the content
but that a textual replacement for the image was not available when the image was generated.
If the image is available and the user agent is configured to display that image, then the element represents the element's image data.
If the image has a src attribute whose value is
the empty string, then the element represents nothing.
Otherwise, the user agent should display some sort of indicator that there is an image that is not being rendered, and may, if requested by the user, or if so configured, or when required to provide contextual information in response to navigation, provide caption information for the image, derived as follows:
If the image has a title attribute whose value is not
the empty string, then return the value of that attribute.
If the image is a descendant of a figure element that has a child
figcaption element, and, ignoring the figcaption element and its
descendants, the figure element has no flow content descendants other
than inter-element whitespace and the img element, then return the
contents of the first such figcaption element.
Return nothing. (There is no caption information.)
src attribute is not set and either the alt attribute is set to the empty string or the alt attribute is not set at allThe element represents nothing.
The element represents the text given by the alt attribute.
The alt attribute does not represent advisory information.
User agents must not present the contents of the alt attribute
in the same way as content of the title attribute.
User agents may always provide the user with the option to display any image, or to prevent any image from being displayed. User agents may also apply heuristics to help the user make use of the image when the user is unable to see it, e.g. due to a visual disability or because they are using a text terminal with no graphics capabilities. Such heuristics could include, for instance, optical character recognition (OCR) of text found within the image.
While user agents are encouraged to repair cases of missing alt attributes, authors must not rely on such behavior. Requirements for providing text to act as an alternative for images are described
in detail below.
The contents of img elements, if any, are ignored for the purposes of
rendering.
The usemap attribute,
if present, can indicate that the image has an associated
image map.
The ismap attribute,
when used on an element that is a descendant of an a element with an href attribute, indicates by its presence that the element
provides access to a server-side image map. This affects how events are handled on the
corresponding a element.
The ismap attribute is a
boolean attribute. The attribute must not be specified
on an element that does not have an ancestor a element
with an href attribute.
The usemap and ismap attributes can result in confusing behavior when used
together with source elements with the media
attribute specified in a picture element.
The img element supports dimension
attributes.
Support in all current engines.
The crossOrigin IDL attribute must
reflect the crossorigin content attribute,
limited to only known values.
HTMLImageElement/referrerPolicy
Support in all current engines.
The referrerPolicy IDL attribute must
reflect the referrerpolicy content
attribute, limited to only known values.
Support in all current engines.
The decoding
IDL attribute must reflect the decoding
content attribute, limited to only known values.
Support in all current engines.
The loading
IDL attribute must reflect the loading content
attribute, limited to only known values.
The fetchPriority IDL attribute
must reflect the fetchpriority content
attribute, limited to only known values.
image.width [ = value ]Support in all current engines.
image.height [ = value ]Support in all current engines.
These attributes return the actual rendered dimensions of the image, or 0 if the dimensions are not known.
They can be set, to change the corresponding content attributes.
image.naturalWidthSupport in all current engines.
image.naturalHeightHTMLImageElement/naturalHeight
Support in all current engines.
These attributes return the natural dimensions of the image, or 0 if the dimensions are not known.
image.completeSupport in all current engines.
Returns true if the image has been completely downloaded or if no image is specified; otherwise, returns false.
image.currentSrcSupport in all current engines.
Returns the image's absolute URL.
image.decode()Support in all current engines.
This method causes the user agent to decode the image in parallel, returning a promise that fulfills when decoding is complete.
The promise will be rejected with an "EncodingError"
DOMException if the image cannot be decoded.
image = new Image([ width [, height ] ])Support in all current engines.
Returns a new img element, with the width
and height attributes set to the values passed in the
relevant arguments, if applicable.
The IDL attributes width and height must return the rendered width and height of the
image, in CSS pixels, if the image is being rendered; or
else the density-corrected natural width and height of the image, in CSS pixels, if the image has density-corrected natural width and
height and is available but is not being
rendered; or else 0, if the image is not available or does
not have density-corrected natural width and height. [CSS]
The IDL attributes naturalWidth and naturalHeight must return
the density-corrected natural width and height of the image, in CSS pixels, if the image has density-corrected natural width and
height and is available, or else 0. [CSS]
Since the density-corrected natural width and height of an image
take into account any orientation specified in its metadata, naturalWidth and naturalHeight reflect the dimensions after applying any
rotation needed to correctly orient the image, regardless of the value of the
'image-orientation' property.
The complete getter steps are:
If any of the following are true:
both the src attribute and the srcset attribute are omitted;
the srcset attribute is omitted and the src attribute's value is the empty string;
the img element's current request's state is completely available and
its pending request is null; or
the img element's current request's state is broken and its
pending request is null,
then return true.
Return false.
The currentSrc IDL attribute must return the
img element's current request's current
URL.
The decode()
method, when invoked, must perform the following steps:
Let promise be a new promise.
Queue a microtask to perform the following steps:
This is done because updating the image data takes place in a microtask as well. Thus, to make code such as
img. src = "stars.jpg" ;
img. decode(); properly decode stars.jpg, we need to delay any processing by one
microtask.
Let global be this's relevant global object.
If any of the following are true:
this's node document is not fully active; or
this's current request's state is broken,
then reject promise with an "EncodingError"
DOMException.
Otherwise, in parallel, wait for one of the following cases to occur, and perform the corresponding actions:
img element's node document stops being fully
activeimg element's current request changes or is mutatedimg element's current request's state becomes brokenQueue a global task on the DOM manipulation task source with
global to reject promise with an
"EncodingError" DOMException.
img element's current request's state becomes completely
availableDecode the image.
If decoding does not need to be performed for this image (for example because it is a vector graphic) or the decoding process completes successfully, then queue a global task on the DOM manipulation task source with global to resolve promise with undefined.
If decoding fails (for example due to invalid image data), then queue a global
task on the DOM manipulation task source with global to
reject promise with an "EncodingError"
DOMException.
User agents should ensure that the decoded media data stays readily available until at least the end of the next successful update the rendering step in the event loop. This is an important part of the API contract, and should not be broken if at all possible. (Typically, this would only be violated in low-memory situations that require evicting decoded image data, or when the image is too large to keep in decoded form for this period of time.)
Animated images will become completely available only after all their frames are loaded. Thus, even though an implementation could decode the first frame before that point, the above steps will not do so, instead waiting until all frames are available.
Return promise.
Without the decode() method, the process of loading an
img element and then displaying it might look like the following:
const img = new Image();
img. src = "nebula.jpg" ;
img. onload = () => {
document. body. appendChild( img);
};
img. onerror = () => {
document. body. appendChild( new Text( "Could not load the nebula :(" ));
}; However, this can cause notable dropped frames, as the paint that occurs after inserting the image into the DOM causes a synchronous decode on the main thread.
This can instead be rewritten using the decode()
method:
const img = new Image();
img. src = "nebula.jpg" ;
img. decode(). then(() => {
document. body. appendChild( img);
}). catch (() => {
document. body. appendChild( new Text( "Could not load the nebula :(" ));
}); This latter form avoids the dropped frames of the original, by allowing the user agent to decode the image in parallel, and only inserting it into the DOM (and thus causing it to be painted) once the decoding process is complete.
Because the decode() method attempts to ensure that the
decoded image data is available for at least one frame, it can be combined with the requestAnimationFrame() API.
This means it can be used with coding styles or frameworks that ensure that all DOM modifications
are batched together as animation frame
callbacks:
const container = document. querySelector( "#container" );
const { containerWidth, containerHeight } = computeDesiredSize();
requestAnimationFrame(() => {
container. style. width = containerWidth;
container. style. height = containerHeight;
});
// ...
const img = new Image();
img. src = "supernova.jpg" ;
img. decode(). then(() => {
requestAnimationFrame(() => container. appendChild( img));
}); A legacy factory function is provided for creating HTMLImageElement objects (in
addition to the factory methods from DOM such as createElement()): Image(width, height). When invoked,
the legacy factory function must perform the following steps:
Let document be the current global object's associated Document.
Let img be the result of creating an
element given document, "img", and the HTML
namespace.
If width is given, then set
an attribute value for img using "width"
and width.
If height is given, then set an attribute value for img
using "height" and height.
Return img.
A single image can have different appropriate alternative text depending on the context.
In each of the following cases, the same image is used, yet the alt text is different each time. The image is the coat of arms of the
Carouge municipality in the canton Geneva in Switzerland.
Here it is used as a supplementary icon:
< p > I lived in < img src = "carouge.svg" alt = "" > Carouge.</ p > Here it is used as an icon representing the town:
< p > Home town: < img src = "carouge.svg" alt = "Carouge" ></ p > Here it is used as part of a text on the town:
< p > Carouge has a coat of arms.</ p >
< p >< img src = "carouge.svg" alt = "The coat of arms depicts a lion, sitting in front of a tree." ></ p >
< p > It is used as decoration all over the town.</ p > Here it is used as a way to support a similar text where the description is given as well as, instead of as an alternative to, the image:
< p > Carouge has a coat of arms.</ p >
< p >< img src = "carouge.svg" alt = "" ></ p >
< p > The coat of arms depicts a lion, sitting in front of a tree.
It is used as decoration all over the town.</ p > Here it is used as part of a story:
< p > She picked up the folder and a piece of paper fell out.</ p >
< p >< img src = "carouge.svg" alt = "Shaped like a shield, the paper had a
red background, a green tree, and a yellow lion with its tongue
hanging out and whose tail was shaped like an S." ></ p >
< p > She stared at the folder. S! The answer she had been looking for all
this time was simply the letter S! How had she not seen that before? It all
came together now. The phone call where Hector had referred to a lion's tail,
the time Maria had stuck her tongue out...</ p > Here it is not known at the time of publication what the image will be, only that it will be a
coat of arms of some kind, and thus no replacement text can be provided, and instead only a brief
caption for the image is provided, in the title attribute:
< p > The last user to have uploaded a coat of arms uploaded this one:</ p >
< p >< img src = "last-uploaded-coat-of-arms.cgi" title = "User-uploaded coat of arms." ></ p > Ideally, the author would find a way to provide real replacement text even in this case, e.g. by asking the previous user. Not providing replacement text makes the document more difficult to use for people who are unable to view images, e.g. blind users, or users or very low-bandwidth connections or who pay by the byte, or users who are forced to use a text-only web browser.
Here are some more examples showing the same picture used in different contexts, with different appropriate alternate texts each time.
< article >
< h1 > My cats</ h1 >
< h2 > Fluffy</ h2 >
< p > Fluffy is my favorite.</ p >
< img src = "fluffy.jpg" alt = "She likes playing with a ball of yarn." >
< p > She's just too cute.</ p >
< h2 > Miles</ h2 >
< p > My other cat, Miles just eats and sleeps.</ p >
</ article > < article >
< h1 > Photography</ h1 >
< h2 > Shooting moving targets indoors</ h2 >
< p > The trick here is to know how to anticipate; to know at what speed and
what distance the subject will pass by.</ p >
< img src = "fluffy.jpg" alt = "A cat flying by, chasing a ball of yarn, can be
photographed quite nicely using this technique." >
< h2 > Nature by night</ h2 >
< p > To achieve this, you'll need either an extremely sensitive film, or
immense flash lights.</ p >
</ article > < article >
< h1 > About me</ h1 >
< h2 > My pets</ h2 >
< p > I've got a cat named Fluffy and a dog named Miles.</ p >
< img src = "fluffy.jpg" alt = "Fluffy, my cat, tends to keep itself busy." >
< p > My dog Miles and I like go on long walks together.</ p >
< h2 > music</ h2 >
< p > After our walks, having emptied my mind, I like listening to Bach.</ p >
</ article > < article >
< h1 > Fluffy and the Yarn</ h1 >
< p > Fluffy was a cat who liked to play with yarn. She also liked to jump.</ p >
< aside >< img src = "fluffy.jpg" alt = "" title = "Fluffy" ></ aside >
< p > She would play in the morning, she would play in the evening.</ p >
</ article > This section is non-normative.
To embed an image in HTML, when there is only a single image resource, use the img
element and its src attribute.
< h2 > From today's featured article</ h2 >
< img src = "/uploads/100-marie-lloyd.jpg" alt = "" width = "100" height = "150" >
< p >< b >< a href = "/wiki/Marie_Lloyd" > Marie Lloyd</ a ></ b > (1870–1922)
was an English < a href = "/wiki/Music_hall" > music hall</ a > singer, ...However, there are a number of situations for which the author might wish to use multiple image resources that the user agent can choose from:
Different users might have different environmental characteristics:
The users' physical screen size might be different from one another.
A mobile phone's screen might be 4 inches diagonally, while a laptop's screen might be 14 inches diagonally.
This is only relevant when an image's rendered size depends on the viewport size.
The users' screen pixel density might be different from one another.
A mobile phone's screen might have three times as many physical pixels per inch compared to another mobile phone's screen, regardless of their physical screen size.
The users' zoom level might be different from one another, or might change for a single user over time.
A user might zoom in to a particular image to be able to get a more detailed look.
The zoom level and the screen pixel density (the previous point) can both affect the number of physical screen pixels per CSS pixel. This ratio is usually referred to as device-pixel-ratio.
The users' screen orientation might be different from one another, or might change for a single user over time.
A tablet can be held upright or rotated 90 degrees, so that the screen is either "portrait" or "landscape".
The users' network speed, network latency and bandwidth cost might be different from one another, or might change for a single user over time.
A user might be on a fast, low-latency and constant-cost connection while at work, on a slow, low-latency and constant-cost connection while at home, and on a variable-speed, high-latency and variable-cost connection anywhere else.
Authors might want to show the same image content but with different rendered size depending on, usually, the width of the viewport. This is usually referred to as viewport-based selection.
A web page might have a banner at the top that always spans the entire viewport width. In this case, the rendered size of the image depends on the physical size of the screen (assuming a maximised browser window).
Another web page might have images in columns, with a single column for screens with a small physical size, two columns for screens with medium physical size, and three columns for screens with big physical size, with the images varying in rendered size in each case to fill up the viewport. In this case, the rendered size of an image might be bigger in the one-column layout compared to the two-column layout, despite the screen being smaller.
Authors might want to show different image content depending on the rendered size of the image. This is usually referred to as art direction.
When a web page is viewed on a screen with a large physical size (assuming a maximised browser window), the author might wish to include some less relevant parts surrounding the critical part of the image. When the same web page is viewed on a screen with a small physical size, the author might wish to show only the critical part of the image.
Authors might want to show the same image content but using different image formats, depending on which image formats the user agent supports. This is usually referred to as image format-based selection.
A web page might have some images in the JPEG, WebP and JPEG XR image formats, with the latter two having better compression abilities compared to JPEG. Since different user agents can support different image formats, with some formats offering better compression ratios, the author would like to serve the better formats to user agents that support them, while providing JPEG fallback for user agents that don't.
The above situations are not mutually exclusive. For example, it is reasonable to combine different resources for different device-pixel-ratio with different resources for art direction.
While it is possible to solve these problems using scripting, doing so introduces some other problems:
Some user agents aggressively download images specified in the HTML markup, before scripts have had a chance to run, so that web pages complete loading sooner. If a script changes which image to download, the user agent will potentially start two separate downloads, which can instead cause worse page loading performance.
If the author avoids specifying any image in the HTML markup and instead instantiates a single download from script, that avoids the double download problem above but then no image will be downloaded at all for users with scripting disabled and the aggressive image downloading optimization will also be disabled.
With this in mind, this specification introduces a number of features to address the above problems in a declarative manner.
The src and srcset
attributes on the img element can be used, using the x
descriptor, to provide multiple images that only vary in their size (the smaller image is a
scaled-down version of the bigger image).
The x descriptor is not appropriate when the rendered
size of the image depends on the viewport width
(viewport-based selection), but can be used together with
art direction.
< h2 > From today's featured article</ h2 >
< img src = "/uploads/100-marie-lloyd.jpg"
srcset = "/uploads/150-marie-lloyd.jpg 1.5x, /uploads/200-marie-lloyd.jpg 2x"
alt = "" width = "100" height = "150" >
< p >< b >< a href = "/wiki/Marie_Lloyd" > Marie Lloyd</ a ></ b > (1870–1922)
was an English < a href = "/wiki/Music_hall" > music hall</ a > singer, ...The user agent can choose any of the given resources depending on the user's screen's pixel density, zoom level, and possibly other factors such as the user's network conditions.
For backwards compatibility with older user agents that don't yet understand the srcset attribute, one of the URLs is specified in the
img element's src attribute. This will result
in something useful (though perhaps lower-resolution than the user would like) being displayed
even in older user agents. For new user agents, the src
attribute participates in the resource selection, as if it was specified in srcset with a 1x descriptor.
The image's rendered size is given in the width and
height attributes, which allows the user agent to
allocate space for the image before it is downloaded.
The srcset and sizes attributes can be used, using the w
descriptor, to provide multiple images that only vary in their size (the smaller image is a
scaled-down version of the bigger image).
In this example, a banner image takes up the entire viewport width (using appropriate CSS).
< h1 >< img sizes = "100vw" srcset = "wolf-400.jpg 400w, wolf-800.jpg 800w, wolf-1600.jpg 1600w"
src = "wolf-400.jpg" alt = "The rad wolf" ></ h1 > The user agent will calculate the effective pixel density of each image from the specified
w descriptors and the specified rendered size in the sizes attribute. It can then choose any of the given resources
depending on the user's screen's pixel density, zoom level, and possibly other factors such as
the user's network conditions.
If the user's screen is 320 CSS pixels wide, this is equivalent
to specifying wolf-400.jpg 1.25x, wolf-800.jpg 2.5x, wolf-1600.jpg 5x.
On the other hand, if the user's screen is 1200 CSS pixels wide,
this is equivalent to specifying wolf-400.jpg 0.33x, wolf-800.jpg 0.67x, wolf-1600.jpg 1.33x. By using the
w descriptors and the sizes
attribute, the user agent can choose the correct image source to download regardless of how
large the user's device is.
For backwards compatibility, one of the URLs is specified in the img element's
src attribute. In new user agents, the src attribute is ignored when the srcset attribute uses w descriptors.
In this example, the web page has three layouts depending on the width of the
viewport. The narrow layout has one column of images (the width of each image is
about 100%), the middle layout has two columns of images (the width of each image is about
50%), and the widest layout has three columns of images, and some page margin (the width of
each image is about 33%). It breaks between these layouts when the viewport is
30em wide and 50em wide, respectively.
< img sizes = "(max-width: 30em) 100vw, (max-width: 50em) 50vw, calc(33vw - 100px)"
srcset = "swing-200.jpg 200w, swing-400.jpg 400w, swing-800.jpg 800w, swing-1600.jpg 1600w"
src = "swing-400.jpg" alt = "Kettlebell Swing" > The sizes attribute sets up the layout breakpoints at
30em and 50em, and declares the image sizes
between these breakpoints to be 100vw, 50vw, or
calc(33vw - 100px). These sizes do not necessarily have to match up
exactly with the actual image width as specified in the CSS.
The user agent will pick a width from the sizes
attribute, using the first item with a <media-condition> (the part in
parentheses) that evaluates to true, or using the last item (calc(33vw -
100px)) if they all evaluate to false.
For example, if the viewport width is 29em, then (max-width: 30em) evaluates to true and 100vw is used,
so the image size, for the purpose of resource selection, is 29em. If
the viewport width is instead 32em, then
(max-width: 30em) evaluates to false, but
(max-width: 50em) evaluates to true
and 50vw is used, so the image size, for the purpose of resource
selection, is 16em (half the viewport width). Notice that
the slightly wider viewport results in a smaller image because of the different
layout.
The user agent can then calculate the effective pixel density and choose an appropriate resource similarly to the previous example.
This example is the same as the previous example, but the image is lazy-loaded. In this case, the sizes attribute can use the auto keyword, and the user agent will use the width attribute (or the width specified in CSS) for the
source size.
< img loading = "lazy" width = "200" height = "200" sizes = "auto"
srcset = "swing-200.jpg 200w, swing-400.jpg 400w, swing-800.jpg 800w, swing-1600.jpg 1600w"
src = "swing-400.jpg" alt = "Kettlebell Swing" > For better backwards-compatibility with legacy user agents that don't support the auto keyword, fallback sizes can be specified if desired.
< img loading = "lazy" width = "200" height = "200"
sizes = "auto, (max-width: 30em) 100vw, (max-width: 50em) 50vw, calc(33vw - 100px)"
srcset = "swing-200.jpg 200w, swing-400.jpg 400w, swing-800.jpg 800w, swing-1600.jpg 1600w"
src = "swing-400.jpg" alt = "Kettlebell Swing" > The picture element and the source element, together with the media attribute, can be used to provide multiple images that
vary the image content (for instance the smaller image might be a cropped version of the bigger
image).
< picture >
< source media = "(min-width: 45em)" srcset = "large.jpg" >
< source media = "(min-width: 32em)" srcset = "med.jpg" >
< img src = "small.jpg" alt = "The wolf runs through the snow." >
</ picture > The user agent will choose the first source element for which the media query
in the media attribute matches, and then choose an
appropriate URL from its srcset attribute.
The rendered size of the image varies depending on which resource is chosen. To specify dimensions that the user agent can use before having downloaded the image, CSS can be used.
img { width : 300 px ; height : 300 px }
@media ( min-width: 32em) { img { width: 500px; height:300px } }
@media (min-width: 45em) { img { width: 700px; height:400px } }This example combines art direction- and device-pixel-ratio-based selection. A banner that takes half the viewport is provided in two versions, one for wide screens and one for narrow screens.
< h1 >
< picture >
< source media = "(max-width: 500px)" srcset = "banner-phone.jpeg, banner-phone-HD.jpeg 2x" >
< img src = "banner.jpeg" srcset = "banner-HD.jpeg 2x" alt = "The Breakfast Combo" >
</ picture >
</ h1 > The type attribute on the source element
can be used to provide multiple images in different formats.
< h2 > From today's featured article</ h2 >
< picture >
< source srcset = "/uploads/100-marie-lloyd.webp" type = "image/webp" >
< source srcset = "/uploads/100-marie-lloyd.jxr" type = "image/vnd.ms-photo" >
< img src = "/uploads/100-marie-lloyd.jpg" alt = "" width = "100" height = "150" >
</ picture >
< p >< b >< a href = "/wiki/Marie_Lloyd" > Marie Lloyd</ a ></ b > (1870–1922)
was an English < a href = "/wiki/Music_hall" > music hall</ a > singer, ...In this example, the user agent will choose the first source that has a type attribute with a supported MIME type. If the user agent
supports WebP images, the first source element will be chosen. If not, but the
user agent does support JPEG XR images, the second source element will be chosen.
If neither of those formats are supported, the img element will be chosen.
This section is non-normative.
CSS and media queries can be used to construct graphical page layouts that adapt dynamically to
the user's environment, in particular to different viewport dimensions and pixel
densities. For content, however, CSS does not help; instead, we have the img element's
srcset attribute and the picture element.
This section walks through a sample case showing how to use these features.
Consider a situation where on wide screens (wider than 600 CSS
pixels) a 300×150 image named a-rectangle.png is to be used,
but on smaller screens (600 CSS pixels and less), a smaller
100×100 image called a-square.png is to be used. The markup for this
would look like this:
< figure >
< picture >
< source srcset = "a-square.png" media = "(max-width: 600px)" >
< img src = "a-rectangle.png" alt = "Barney Frank wears a suit and glasses." >
</ picture >
< figcaption > Barney Frank, 2011</ figcaption >
</ figure > For details on what to put in the alt
attribute, see the Requirements for providing text to act as an alternative for
images section.
The problem with this is that the user agent does not necessarily know what dimensions to use for the image when the image is loading. To avoid the layout having to be reflowed multiple times as the page is loading, CSS and CSS media queries can be used to provide the dimensions:
< style >
# a { width : 300 px ; height : 150 px ; }
@ media ( max-width : 600px ) { # a { width : 100 px ; height : 100 px ; } }
</ style >
< figure >
< picture >
< source srcset = "a-square.png" media = "(max-width: 600px)" >
< img src = "a-rectangle.png" alt = "Barney Frank wears a suit and glasses." id = "a" >
</ picture >
< figcaption > Barney Frank, 2011</ figcaption >
</ figure > Alternatively, the width and height attributes can be used on the source and
img elements to provide the width and height:
< figure >
< picture >
< source srcset = "a-square.png" media = "(max-width: 600px)" width = "100" height = "100" >
< img src = "a-rectangle.png" width = "300" height = "150"
alt = "Barney Frank wears a suit and glasses." >
</ picture >
< figcaption > Barney Frank, 2011</ figcaption >
</ figure >
The img element is used with the src attribute,
which gives the URL of the image to use for legacy user agents that do not support the
picture element. This leads to a question of which image to provide in the src attribute.
If the author wants the biggest image in legacy user agents, the markup could be as follows:
< picture >
< source srcset = "pear-mobile.jpeg" media = "(max-width: 720px)" >
< source srcset = "pear-tablet.jpeg" media = "(max-width: 1280px)" >
< img src = "pear-desktop.jpeg" alt = "The pear is juicy." >
</ picture > However, if legacy mobile user agents are more important, one can list all three images in the
source elements, overriding the src attribute
entirely.
< picture >
< source srcset = "pear-mobile.jpeg" media = "(max-width: 720px)" >
< source srcset = "pear-tablet.jpeg" media = "(max-width: 1280px)" >
< source srcset = "pear-desktop.jpeg" >
< img src = "pear-mobile.jpeg" alt = "The pear is juicy." >
</ picture > Since at this point the src attribute is actually being
ignored entirely by picture-supporting user agents, the src attribute can default to any image, including one that is neither
the smallest nor biggest:
< picture >
< source srcset = "pear-mobile.jpeg" media = "(max-width: 720px)" >
< source srcset = "pear-tablet.jpeg" media = "(max-width: 1280px)" >
< source srcset = "pear-desktop.jpeg" >
< img src = "pear-tablet.jpeg" alt = "The pear is juicy." >
</ picture > Above the max-width media feature is used, giving the maximum
(viewport) dimensions that an image is intended for. It is also possible to use min-width instead.
< picture >
< source srcset = "pear-desktop.jpeg" media = "(min-width: 1281px)" >
< source srcset = "pear-tablet.jpeg" media = "(min-width: 721px)" >
< img src = "pear-mobile.jpeg" alt = "The pear is juicy." >
</ picture > source,
img, and link elementsA srcset attribute is an attribute with requirements defined in this section.
If present, its value must consist of one or more image candidate strings, each separated from the next by a U+002C COMMA character (,). If an image candidate string contains no descriptors and no ASCII whitespace after the URL, the following image candidate string, if there is one, must begin with one or more ASCII whitespace.
An image candidate string consists of the following components, in order, with the further restrictions described below this list:
Zero or more ASCII whitespace.
A valid non-empty URL that does not start or end with a U+002C COMMA character (,), referencing a non-interactive, optionally animated, image resource that is neither paged nor scripted.
Zero or more ASCII whitespace.
Zero or one of the following:
A width descriptor, consisting of: ASCII whitespace, a valid non-negative integer giving a number greater than zero representing the width descriptor value, and a U+0077 LATIN SMALL LETTER W character.
A pixel density descriptor, consisting of: ASCII whitespace, a valid floating-point number giving a number greater than zero representing the pixel density descriptor value, and a U+0078 LATIN SMALL LETTER X character.
Zero or more ASCII whitespace.
There must not be an image candidate string for an element that has the same width descriptor value as another image candidate string's width descriptor value for the same element.
There must not be an image candidate string for an element that has the same
pixel density descriptor value as another image candidate string's
pixel density descriptor value for the same element. For the purpose of this
requirement, an image candidate string with no descriptors is equivalent to an
image candidate string with a 1x descriptor.
If an image candidate string for an element has the width descriptor specified, all other image candidate strings for that element must also have the width descriptor specified.
The specified width in an image candidate string's width descriptor must match the natural width in the resource given by the image candidate string's URL, if it has a natural width.
If an element has a sizes attribute present, all image candidate strings for that element must have the width descriptor specified.
A sizes attribute is an attribute with requirements defined in this section.
If present, the value must be a valid source size list.
A valid source size list is a string that matches the following grammar: [CSSVALUES] [MQ]
< source-size-list > = < source-size > #? , < source-size-value >
< source-size > = < media-condition > < source-size-value > | auto
< source-size-value > = < length > | autoA <source-size-value> that is a <length> must not be negative, and must not use CSS functions other than the math functions.
The keyword auto is a width that is
computed in parse a sizes attribute. If present, it must be the first entry and the
entire <source-size-list> value must either be the string "auto" (ASCII case-insensitive) or start with the string "auto," (ASCII case-insensitive).
If the img element that initiated the image loading (with the
update the image data or react to environment
changes algorithms) allows auto-sizes and is being rendered,
then auto is the concrete object size width.
Otherwise, the auto value is ignored and the next
source size is used instead, if any.
The auto keyword may be specified in the sizes attribute of source elements and sizes attribute of img elements, if the following
conditions are met. Otherwise, auto must not be
specified.
The element is a source element with a following sibling
img element.
The element is an img element.
The img element referenced in either condition above allows
auto-sizes.
In addition, it is strongly encouraged to specify dimensions using the width and height attributes
or with CSS. Without specified dimensions, the image will likely render with 300x150 dimensions
because sizes="auto" implies contain-intrinsic-size: 300px
150px in the Rendering section.
The <source-size-value> gives the intended layout width of the image. The author can specify different widths for different environments with <media-condition>s.
Percentages are not allowed in a <source-size-value>, to avoid confusion about what it would be relative to. The 'vw' unit can be used for sizes relative to the viewport width.
An img element has a current request and a pending request.
The current request is initially set to a new image request.
The pending request is initially set to null.
An image request has a state, current URL, and image data.
An image request's state is one of the following:
An image request's current URL is initially the empty string.
An image request's image data is the decoded image data.
When an image request's state is either partially available or completely available, the image request is said to be available.
When an img element's current request's state is completely available and the
user agent can decode the media data without errors, then the img element is said to
be fully decodable.
An image request's state is initially unavailable.
When an img element's current request is available, the img element provides a paint
source whose width is the image's density-corrected natural width (if any), whose height is the image's density-corrected natural height
(if any), and whose appearance is the natural appearance of the image.
An img element is said to use srcset or
picture if it has a srcset attribute
specified or if it has a parent that is a picture element.
Each img element has a last selected source, which must initially be
null.
Each image request has a current pixel density, which must initially be 1.
Each image request has preferred density-corrected dimensions, which is either a struct consisting of a width and a height or is null. It must initially be null.
To determine the density-corrected
natural width and height of an img element img:
Let dim be img's current request's preferred density-corrected dimensions.
The preferred density-corrected dimensions are set in the prepare an image for presentation algorithm based on meta information in the image.
If dim is null, set dim to img's natural dimensions.
Set dim's width to dim's width divided by img's current request's current pixel density.
Set dim's height to dim's height divided by img's current request's current pixel density.
Return dim.
For example, if the current pixel density is 3.125, that means that there are 300 device pixels per CSS inch, and thus if the image data is 300x600, it has density-corrected natural width and height of 96 CSS pixels by 192 CSS pixels.
All img and link elements are associated with a source set.
A source set is an ordered set of zero or more image sources and a source size.
An image source is a URL, and optionally either a pixel density descriptor, or a width descriptor.
A source size is a <source-size-value>.
When a source size has a unit relative to the viewport,
it must be interpreted relative to the img element's node document's
viewport. Other units must be interpreted the same as in Media Queries.
[MQ]
A parse error for algorithms in this section indicates a non-fatal mismatch between input and requirements. User agents are encouraged to expose parse errors somehow.
Whether the image is fetched successfully or not (e.g. whether the response status was an ok status) must be ignored when determining the image's type and whether it is a valid image.
This allows servers to return images with error responses, and have them displayed.
The user agent should apply the image sniffing rules to determine the type of the image, with the image's associated Content-Type headers giving the official type. If these rules are not applied, then the type of the image must be the type given by the image's associated Content-Type headers.
User agents must not support non-image resources with the img element (e.g. XML
files whose document element is an HTML element). User agents must not run executable
code (e.g. scripts) embedded in the image resource. User agents must only display the first page
of a multipage resource (e.g. a PDF file). User agents must not allow the resource to act in an
interactive fashion, but should honour any animation in the resource.
This specification does not specify which image types are to be supported.
By default, images are obtained immediately. User agents may provide users with the option to instead obtain them on-demand. (The on-demand option might be used by bandwidth-constrained users, for example.)
When obtaining images immediately, the user agent must synchronously update the image
data of the img element, with the restart animation flag set if so
stated, whenever that element is created or has experienced relevant mutations.
When obtaining images on demand, the user agent must update the image data of an
img element whenever it needs the image data (i.e., on demand), but only if the
img element's current request's state is unavailable. When an
img element has experienced relevant mutations, if the user agent only
obtains images on demand, the img element's current request's state must return to unavailable.
The relevant mutations for an img element are as follows:
The element's src, srcset, width, or sizes attributes are set, changed, or removed.
The element's src attribute is set to the same value as the previous value.
This must set the restart animation flag for the update the image data algorithm.
The element's crossorigin attribute's state is changed.
The element's referrerpolicy attribute's
state is changed.
The img or source HTML element insertion steps,
HTML element removing steps, and HTML element moving steps count the
mutation as a relevant mutation.
The element's parent is a picture element and a source element
that is a previous sibling has its srcset, sizes, media, type, width or height attributes set, changed, or removed.
The element's adopting steps are run.
If the element allows auto-sizes: the element starts or stops being rendered, or its concrete object size width changes. This must set the maybe omit events flag for the update the image data algorithm.
Each Document object must have a list of available images. Each image
in this list is identified by a tuple consisting of an absolute URL, a CORS
settings attribute mode, and, if the mode is not No
CORS, an origin.
Each image furthermore has an ignore higher-layer caching flag.
User agents may copy entries from one Document
object's list of available images to another at any time (e.g. when the
Document is created, user agents can add to it all the images that are loaded in
other Documents), but must not change the keys of entries copied in this way when
doing so, and must unset the ignore higher-layer caching flag for the copied entry.
User agents may also remove images from such lists at any time (e.g. to save
memory).
User agents must remove entries in the list of available images as appropriate
given higher-layer caching semantics for the resource (e.g. the HTTP `Cache-Control` response header) when the ignore
higher-layer caching flag is unset.
The list of available images is intended to enable synchronous
switching when changing the src attribute to a URL that has
previously been loaded, and to avoid re-downloading images in the same document even when they
don't allow caching per HTTP. It is not used to avoid re-downloading the same image while the
previous image is still loading.
The user agent can also store the image data separately from the list of available images.
For example, if a resource has the HTTP response header
`Cache-Control: must-revalidate`, and its ignore higher-layer
caching flag is unset, the user agent would remove it from the list of available
images but could keep the image data separately, and use that if the server responds with a
304 Not Modified status.
Image data is usually encoded in order to reduce file size. This means that in order for the user agent to present the image to the screen, the data needs to be decoded. Decoding is the process which converts an image's media data into a bitmap form, suitable for presentation to the screen. Note that this process can be slow relative to other processes involved in presenting content. Thus, the user agent can choose when to perform decoding, in order to create the best user experience.
Image decoding is said to be synchronous if it prevents presentation of other content until it is finished. Typically, this has an effect of atomically presenting the image and any other content at the same time. However, this presentation is delayed by the amount of time it takes to perform the decode.
Image decoding is said to be asynchronous if it does not prevent presentation of other content. This has an effect of presenting non-image content faster. However, the image content is missing on screen until the decode finishes. Once the decode is finished, the screen is updated with the image.
In both synchronous and asynchronous decoding modes, the final content is presented to screen after the same amount of time has elapsed. The main difference is whether the user agent presents non-image content ahead of presenting the final content.
In order to aid the user agent in deciding whether to perform synchronous or asynchronous
decode, the decoding attribute can be set on
img elements. The possible values of the decoding attribute are the following image decoding
hint keywords:
| Keyword | State | Description |
|---|---|---|
sync
| Sync | Indicates a preference to decode this image synchronously for atomic presentation with other content. |
async
| Async | Indicates a preference to decode this image asynchronously to avoid delaying presentation of other content. |
auto
| Auto | Indicates no preference in decoding mode (the default). |
When decoding an image, the user agent should
respect the preference indicated by the decoding
attribute's state. If the state indicated is Auto, then the user agent is free to choose any
decoding behavior.
It is also possible to control the decoding behavior using the decode() method. Since the decode() method performs decoding independently from the process responsible for
presenting content to screen, it is unaffected by the decoding attribute.
This algorithm cannot be called from steps running in parallel. If a user agent needs to call this algorithm from steps running in parallel, it needs to queue a task to do so.
When the user agent is to update the image data of an img element,
optionally with the restart animations flag set, optionally with the maybe omit
events flag set, it must run the following steps:
If the element's node document is not fully active, then:
Continue running this algorithm in parallel.
Wait until the element's node document is fully active.
If another instance of this algorithm for this img element was started after this instance
(even if it aborted and is no longer running), then return.
Queue a microtask to continue this algorithm.
If the user agent cannot support images, or its support for images has been disabled, then abort the image request for the current request and the pending request, set the current request's state to unavailable, set the pending request to null, and return.
Let previousURL be the current request's current URL.
Let selected source be null and selected pixel density be undefined.
If the element does not use srcset or picture and
it has a src attribute specified whose value is not the empty
string, then set selected source to the value of the element's src attribute and set selected pixel density to
1.0.
Set the element's last selected source to selected source.
If selected source is not null, then:
Let urlString be the result of encoding-parsing-and-serializing a URL given selected source, relative to the element's node document.
If urlString is failure, then abort this inner set of steps.
Let key be a tuple consisting of urlString, the img
element's crossorigin attribute's mode, and, if that
mode is not No CORS, the node
document's origin.
If the list of available images contains an entry for key, then:
Set the ignore higher-layer caching flag for that entry.
Abort the image request for the current request and the pending request.
Set the pending request to null.
Set the current request to a new image request whose image data is that of the entry and whose state is completely available.
Prepare the current request
for presentation given the img element.
Set the current request's current pixel density to selected pixel density.
Queue an element task on the DOM manipulation task source
given the img element and the following steps:
If restart animation is set, then restart the animation.
Set the current request's current URL to urlString.
If maybe omit events is not set or previousURL is not equal to
urlString, then fire an event named
load at the img element.
Abort the update the image data algorithm.
Queue a microtask to perform the rest of this algorithm, allowing the task that invoked this algorithm to continue.
If another instance of this algorithm for this img element was started after
this instance (even if it aborted and is no longer running), then return.
Only the last instance takes effect, to avoid multiple requests when, for
example, the src, srcset,
and crossorigin attributes are all set in
succession.
Let selected source and selected pixel density be the URL and pixel density that results from selecting an image source, respectively.
If selected source is null, then:
Set the current request's state to broken, abort the image request for the current request and the pending request, and set the pending request to null.
Queue an element task on the DOM manipulation task source given
the img element and the following steps:
Change the current request's current URL to the empty string.
If all of the following are true:
the element has a src attribute or it uses srcset or
picture; and
maybe omit events is not set or previousURL is not the empty string,
then fire an event named error at the img element.
Return.
Let urlString be the result of encoding-parsing-and-serializing a URL given selected source, relative to the element's node document.
If urlString is failure, then:
Abort the image request for the current request and the pending request.
Set the current request's state to broken.
Set the pending request to null.
Queue an element task on the DOM manipulation task
source given the img element and the following steps:
Change the current request's current URL to selected source.
If maybe omit events is not set or previousURL is not equal to
selected source, then fire an event
named error at the img element.
Return.
If the pending request is not null and urlString is the same as the pending request's current URL, then return.
If urlString is the same as the current request's current URL and the current request's state is partially available, then
abort the image request for the pending request, queue an element
task on the DOM manipulation task source given the img element
to restart the animation if restart animation is set, and return.
Abort the image request for the pending request.
Set image request to a new image request whose current URL is urlString.
If the current request's state is unavailable or broken, then set the current request to image request. Otherwise, set the pending request to image request.
Let request be the result of creating a potential-CORS request given urlString, "image", and the current state of the element's crossorigin content attribute.
Set request's client to the element's node document's relevant settings object.
If the element uses srcset or
picture, set request's initiator to "imageset".
Set request's referrer
policy to the current state of the element's referrerpolicy attribute.
Set request's priority to the current state of the
element's fetchpriority attribute.
Let delay load event be true if the img's lazy loading
attribute is in the Eager state, or if
scripting is disabled for the img, and
false otherwise.
If the will lazy load element steps given the img return true,
then:
Set the img's lazy load resumption steps to the rest of this
algorithm starting with the step labeled fetch the image.
Start intersection-observing a lazy loading element for the
img element.
Return.
Fetch the image: Fetch request. Return from this algorithm, and run the remaining steps as part of the fetch's processResponse for the response response.
The resource obtained in this fashion, if any, is image request's image data. It can be either CORS-same-origin or
CORS-cross-origin; this affects the image's interaction with other APIs (e.g.,
when used on a canvas).
When delay load event is true, fetching the image must delay the load event of the element's node document until the task that is queued by the networking task source once the resource has been fetched (defined below) has been run.
This, unfortunately, can be used to perform a rudimentary port scan of the user's local network (especially in conjunction with scripting, though scripting isn't actually necessary to carry out such an attack). User agents may implement cross-origin access control policies that are stricter than those described above to mitigate this attack, but unfortunately such policies are typically not compatible with existing web content.
As soon as possible, jump to the first applicable entry from the following list:
multipart/x-mixed-replaceThe next task that is queued by the networking task source while the image is being fetched must run the following steps:
If image request is the pending request and at least one body part has been completely decoded, abort the image request for the current request, and upgrade the pending request to the current request.
Otherwise, if image request is the pending request and the user agent is able to determine that image request's image is corrupted in some fatal way such that the image dimensions cannot be obtained, abort the image request for the current request, upgrade the pending request to the current request, and set the current request's state to broken.
Otherwise, if image request is the current request, its state is unavailable, and the user agent is able to determine image request's image's width and height, set the current request's state to partially available.
Otherwise, if image request is the current request, its state is unavailable, and the user agent is able to determine that image request's image is corrupted in some fatal way such that the image dimensions cannot be obtained, set the current request's state to broken.
Each task that is queued by the networking task source while the image is being
fetched must update the presentation of the image, but as each new body part comes in, if the
user agent is able to determine the image's width and height, it must prepare the img element's current request
for presentation given the img element and replace the previous image.
Once one body part has been completely decoded, perform the following steps:
Set the img element's current request's state to completely
available.
If maybe omit events is not set or previousURL is not equal to
urlString, then queue an element task on the DOM manipulation task source
given the img element to fire an event
named load at the img element.
The next task that is queued by the networking task source while the image is being fetched must run the following steps:
If the user agent is able to determine image request's image's width and height, and image request is the pending request, set image request's state to partially available.
Otherwise, if the user agent is able to determine image request's image's
width and height, and image request is the current request, prepare image request for
presentation given the img element and set image request's
state to partially
available.
Otherwise, if the user agent is able to determine that image request's image is corrupted in some fatal way such that the image dimensions cannot be obtained, and image request is the pending request:
Abort the image request for the current request and the pending request.
Set the current request's state to broken.
Fire an event named error at the img element.
Otherwise, if the user agent is able to determine that image request's image is corrupted in some fatal way such that the image dimensions cannot be obtained, and image request is the current request:
Abort the image request for image request.
If maybe omit events is not set or previousURL is not equal to
urlString, then fire an event named
error at the img element.
That task, and each subsequent task, that is queued by the networking task source while the image is being fetched, if image request is the current request, must update the presentation of the image appropriately (e.g., if the image is a progressive JPEG, each packet can improve the resolution of the image).
Furthermore, the last task that is queued by the networking task source once the resource has been fetched must additionally run these steps:
If image request is the pending request,
abort the image request for the current request,
upgrade the pending request to the current request, and
prepare image request for
presentation given the img element.
Set image request to the completely available state.
Add the image to the list of available images using the key key, with the ignore higher-layer caching flag set.
If maybe omit events is not set or previousURL is not equal to
urlString, then fire an event named
load at the img element.
The image data is not in a supported file format; the user agent must set image
request's state to broken, abort the image request for the current
request and the pending request, upgrade the pending request to the
current request if image request is the pending request, and
then, if maybe omit events is not set or previousURL is not equal to
urlString, queue an element task on the DOM manipulation task
source given the img element to fire an
event named error at the img
element.
While a user agent is running the above algorithm for an element x, there must be a strong reference from the element's node document to the element x, even if that element is not connected.
To abort the image request for an image request or null image request means to run the following steps:
If image request is null, then return.
Forget image request's image data, if any.
Abort any instance of the fetching algorithm for image request, discarding any pending tasks generated by that algorithm.
To upgrade the pending request to the current request for an img element means to run the following steps:
Set the img element's current request to the pending request.
Set the img element's pending request to null.
To prepare an image for presentation for an image request req given image element img:
Let exifTagMap be the EXIF tags obtained from req's image data, as defined by the relevant codec. [EXIF]
Let physicalWidth and physicalHeight be the width and height obtained from req's image data, as defined by the relevant codec.
Let dimX be the value of exifTagMap's tag 0xA002 (PixelXDimension).
Let dimY be the value of exifTagMap's tag 0xA003 (PixelYDimension).
Let resX be the value of exifTagMap's tag 0x011A (XResolution).
Let resY be the value of exifTagMap's tag 0x011B (YResolution).
Let resUnit be the value of exifTagMap's tag 0x0128 (ResolutionUnit).
If either dimX or dimY is not a positive integer, then return.
If either resX or resY is not a positive floating-point number, then return.
If resUnit is not equal to 2 (Inch), then return.
Let widthFromDensity be the value of physicalWidth, multiplied by 72 and divided by resX.
Let heightFromDensity be the value of physicalHeight, multiplied by 72 and divided by resY.
If widthFromDensity is not equal to dimX or heightFromDensity is not equal to dimY, then return.
If req's image data is CORS-cross-origin, then set img's natural dimensions to dimX and dimY, scale img's pixel data accordingly, and return.
Set req's preferred density-corrected dimensions to a struct with its width set to dimX and its height set to dimY.
Update req's img element's presentation appropriately.
Resolution in EXIF is equivalent to CSS points per inch, therefore 72 is the base for computing size from resolution.
It is not yet specified what would be the case if EXIF arrives after the image is already presented. See issue #4929.
To select an image source given an img element el:
Update the source set for el.
If el's source set is empty, return null as the URL and undefined as the pixel density.
Return the result of selecting an image from el's source set.
To select an image source from a source set given a source set sourceSet:
If an entry b in sourceSet has the same associated pixel density descriptor as an earlier entry a in sourceSet, then remove entry b. Repeat this step until none of the entries in sourceSet have the same associated pixel density descriptor as an earlier entry.
In an implementation-defined manner, choose one image source from sourceSet. Let selectedSource be this choice.
Return selectedSource and its associated pixel density.
When asked to create a source set given a string default source, a string srcset, a string sizes, and an element or null img:
Let source set be an empty source set.
If srcset is not an empty string, then set source set to the result of parsing srcset.
Set source set's source size to the result of parsing sizes with img.
If default source is not the empty string and source set does not contain an image source with a pixel density descriptor value of 1, and no image source with a width descriptor, append default source to source set.
Normalize the source densities of source set.
Return source set.
When asked to update the source set for a given img or
link element el, user agents must do the following:
Set el's source set to an empty source set.
Let elements be « el ».
If el is an img element whose parent node is a
picture element, then replace the contents of
elements with el's parent node's child elements, retaining relative
order.
Let img be el if el is an img element,
otherwise null.
For each child in elements:
If child is el:
Let default source be the empty string.
Let srcset be the empty string.
Let sizes be the empty string.
If el is an img element that has a srcset attribute, then set srcset to that
attribute's value.
Otherwise, if el is a link element that has an imagesrcset attribute, then set srcset to
that attribute's value.
If el is an img element that has a sizes attribute, then set sizes to that attribute's
value.
Otherwise, if el is a link element that has an imagesizes attribute, then set sizes to that
attribute's value.
If el is an img element that has a src attribute, then set default source to that
attribute's value.
Otherwise, if el is a link element that has an href attribute, then set default source to that
attribute's value.
Set el's source set to the result of creating a source set given default source, srcset, sizes, and img.
Return.
If el is a link element, then elements
contains only el, so this step will be reached immediately and the rest of the
algorithm will not run.
If child does not have a srcset
attribute, continue to the next child.
Parse child's srcset attribute and let source set be the returned source set.
If source set has zero image sources, continue to the next child.
If child has a media attribute, and
its value does not match the environment,
continue to the next child.
Parse child's sizes attribute with img, and let source set's source size be the returned value.
If child has a type attribute, and its
value is an unknown or unsupported MIME type, continue to the next child.
If child has width or height attributes, set el's dimension attribute source to
child. Otherwise, set el's dimension attribute source to
el.
Normalize the source densities of source set.
Set el's source set to source set.
Return.
Each img element independently considers its previous sibling
source elements plus the img element itself for selecting an image
source, ignoring any other (invalid) elements, including other img elements in
the same picture element, or source elements that are following siblings
of the relevant img element.
When asked to parse a srcset attribute from an element, parse the value of the element's srcset attribute as follows:
Let input be the value passed to this algorithm.
Let position be a pointer into input, initially pointing at the start of the string.
Let candidates be an initially empty source set.
Splitting loop: Collect a sequence of code points that are ASCII whitespace or U+002C COMMA characters from input given position. If any U+002C COMMA characters were collected, that is a parse error.
If position is past the end of input, return candidates.
Collect a sequence of code points that are not ASCII whitespace from input given position, and let url be the result.
Let descriptors be a new empty list.
If url ends with U+002C (,), then:
Remove all trailing U+002C COMMA characters from url. If this removed more than one character, that is a parse error.
Otherwise:
Descriptor tokenizer: Skip ASCII whitespace within input given position.
Let current descriptor be the empty string.
Let state be in descriptor.
Let c be the character at position. Do the following depending on the value of state. For the purpose of this step, "EOF" is a special character representing that position is past the end of input.
Do the following, depending on the value of c:
If current descriptor is not empty, append current descriptor to descriptors and let current descriptor be the empty string. Set state to after descriptor.
Advance position to the next character in input. If current descriptor is not empty, append current descriptor to descriptors. Jump to the step labeled descriptor parser.
Append c to current descriptor. Set state to in parens.
If current descriptor is not empty, append current descriptor to descriptors. Jump to the step labeled descriptor parser.
Append c to current descriptor.
Do the following, depending on the value of c:
Append c to current descriptor. Set state to in descriptor.
Append current descriptor to descriptors. Jump to the step labeled descriptor parser.
Append c to current descriptor.
Do the following, depending on the value of c:
Stay in this state.
Jump to the step labeled descriptor parser.
Set state to in descriptor. Set position to the previous character in input.
Advance position to the next character in input. Repeat this step.
In order to be compatible with future additions, this algorithm supports multiple descriptors and descriptors with parens.
Descriptor parser: Let error be no.
Let width be absent.
Let density be absent.
Let future-compat-h be absent.
For each descriptor in descriptors, run the appropriate set of steps from the following list:
If the user agent does not support the sizes attribute,
let error be yes.
A conforming user agent will support the sizes attribute.
However, user agents typically implement and ship features in an incremental manner in practice.
If width and density are not both absent, then let error be yes.
Apply the rules for parsing non-negative integers to the descriptor. If the result is 0, let error be yes. Otherwise, let width be the result.
If width, density and future-compat-h are not all absent, then let error be yes.
Apply the rules for parsing floating-point number values to the descriptor. If the result is less than 0, let error be yes. Otherwise, let density be the result.
If density is 0, the natural dimensions will be infinite. User agents are expected to have limits in how big images can be rendered.
This is a parse error.
If future-compat-h and density are not both absent, then let error be yes.
Apply the rules for parsing non-negative integers to the descriptor. If the result is 0, let error be yes. Otherwise, let future-compat-h be the result.
Let error be yes.
If future-compat-h is not absent and width is absent, let error be yes.
If error is still no, then append a new image source to candidates whose URL is url, associated with a width width if not absent and a pixel density density if not absent. Otherwise, there is a parse error.
Return to the step labeled splitting loop.
When asked to parse a sizes attribute from an element element, with an
img element or null img:
Let unparsed sizes list be the result of parsing a comma-separated list of component values from the value of element's sizes attribute (or the empty string, if the attribute is absent). [CSSSYNTAX]
Let size be null.
For each unparsed size in unparsed sizes list:
Remove all consecutive <whitespace-token>s from the end of unparsed size. If unparsed size is now empty, then that is a parse error; continue.
If the last component value in unparsed size is a valid non-negative <source-size-value>, then set size to its value and remove the component value from unparsed size. Any CSS function other than the math functions is invalid. Otherwise, there is a parse error; continue.
If size is auto, and img
is not null, and img is being rendered, and img
allows auto-sizes, then set size to the concrete object
size width of img, in CSS pixels.
If size is still auto,
then it will be ignored.
Remove all consecutive <whitespace-token>s from the end of unparsed size. If unparsed size is now empty:
If this was not the last item in unparsed sizes list, that is a parse error.
If size is not auto, then return
size. Otherwise, continue.
Parse the remaining component values in unparsed size as a <media-condition>. If it does not parse correctly, or it does parse correctly but the <media-condition> evaluates to false, continue. [MQ]
If size is not auto, then return
size. Otherwise, continue.
Return 100vw.
It is invalid to use a bare <source-size-value> that is a <length>
(without an accompanying <media-condition>)
as an entry in the <source-size-list> that is not the last entry.
However, the parsing algorithm allows it at any point in the <source-size-list>,
and will accept it immediately as the size
if the preceding entries in the list weren't used.
This is to enable future extensions,
and protect against simple author errors such as a final trailing comma.
A bare auto keyword is allowed to have other entries
following it to provide a fallback for legacy user agents.
An image source can have a pixel density descriptor, a width descriptor, or no descriptor at all accompanying its URL. Normalizing a source set gives every image source a pixel density descriptor.
When asked to normalize the source densities of a source set source set, the user agent must do the following:
Let source size be source set's source size.
For each image source in source set:
If the image source has a pixel density descriptor, continue to the next image source.
Otherwise, if the image source has a width descriptor, replace the width
descriptor with a pixel density descriptor with a value of the width descriptor value divided by source size and a unit
of x.
If the source size is 0, then the density would be infinity, which results in the natural dimensions being 0 by 0.
Otherwise, give the image source a pixel density descriptor of 1x.
The user agent may at any time run the following algorithm to update an img
element's image in order to react to changes in the
environment. (User agents are not required to ever run this algorithm; for example,
if the user is not looking at the page any more, the user agent might want to wait until the user
has returned to the page before determining which image to use, in case the environment changes
again in the meantime.)
User agents are encouraged to run this algorithm in particular when the user changes
the viewport's size (e.g. by resizing the window or changing the page zoom), and when
an img element is inserted into a
document, so that the density-corrected natural width and height match the
new viewport, and so that the correct image is chosen when art direction
is involved.
Await a stable state. The synchronous section consists of all the remaining steps of this algorithm until the algorithm says the synchronous section has ended. (Steps in synchronous sections are marked with ⌛.)
⌛ If the img element does not use srcset or
picture, its node document is not fully active, it has
image data whose resource type is multipart/x-mixed-replace, or its pending
request is not null, then return.
⌛ Let selected source and selected pixel density be the URL and pixel density that results from selecting an image source, respectively.
⌛ If selected source is null, then return.
⌛ If selected source and selected pixel density are the same as the element's last selected source and current pixel density, then return.
⌛ Let urlString be the result of encoding-parsing-and-serializing a URL given selected source, relative to the element's node document.
⌛ If urlString is failure, then return.
⌛ Let corsAttributeState be the state of the element's crossorigin content attribute.
⌛ Let origin be the img element's node
document's origin.
⌛ Let client be the img element's node
document's relevant settings object.
⌛ Let key be a tuple consisting of urlString, corsAttributeState, and, if corsAttributeState is not No CORS, origin.
⌛ Let image request be a new image request whose current URL is urlString.
⌛ Set the element's pending request to image request.
End the synchronous section, continuing the remaining steps in parallel.
If the list of available images contains an entry for key, then set image request's image data to that of the entry. Continue to the next step.
Otherwise:
Let request be the result of creating a potential-CORS request given
urlString, "image", and
corsAttributeState.
Set request's client to
client, set request's initiator to "imageset", and set request's synchronous
flag.
Set request's
referrer policy to the current state of
the element's referrerpolicy attribute.
Set request's priority to the current state of the element's fetchpriority attribute.
Let response be the result of fetching request.
If response's unsafe response is a network error or
if the image format is unsupported (as determined by applying the image sniffing rules, again as mentioned earlier),
or if the user agent is able to determine that image request's image is corrupted in
some fatal way such that the image dimensions cannot be obtained, or if the resource type is
multipart/x-mixed-replace, then set the pending request to null and abort
these steps.
Otherwise, response's unsafe response is image
request's image data. It can be either
CORS-same-origin or CORS-cross-origin; this affects the image's
interaction with other APIs (e.g., when used on a canvas).
Queue an element task on the DOM manipulation task source given
the img element and the following steps:
If the img element has experienced relevant mutations
since this algorithm started, then set the pending request to null and abort these
steps.
Set the img element's last selected source to selected
source and the img element's current pixel density to
selected pixel density.
Set the image request's state to completely available.
Add the image to the list of available images using the key key, with the ignore higher-layer caching flag set.
Prepare image request for
presentation given the img element.
Fire an event named load at the img element.
Except where otherwise specified, the alt attribute must be
specified and its value must not be empty; the value must be an appropriate replacement for the
image. The specific requirements for the alt attribute depend on
what the image is intended to represent, as described in the following sections.
The most general rule to consider when writing alternative text is the following: the
intent is that replacing every image with the text of its alt
attribute does not change the meaning of the page.
So, in general, alternative text can be written by considering what one would have written had one not been able to include the image.
A corollary to this is that the alt attribute's value should
never contain text that could be considered the image's caption, title, or
legend. It is supposed to contain replacement text that could be used by users
instead of the image; it is not meant to supplement the image. The title attribute can be used for supplemental information.
Another corollary is that the alt attribute's value should
not repeat information that is already provided in the prose next to the image.
One way to think of alternative text is to think about how you would read the page containing the image to someone over the phone, without mentioning that there is an image present. Whatever you say instead of the image is typically a good start for writing the alternative text.
When an a element that creates a hyperlink, or a button
element, has no textual content but contains one or more images, the alt attributes must contain text that together convey the purpose of
the link or button.
In this example, a user is asked to pick their preferred color from a list of three. Each color is given by an image, but for users who have configured their user agent not to display images, the color names are used instead:
< h1 > Pick your color</ h1 >
< ul >
< li >< a href = "green.html" > < img src = "green.jpeg" alt = "Green" > </ a ></ li >
< li >< a href = "blue.html" > < img src = "blue.jpeg" alt = "Blue" > </ a ></ li >
< li >< a href = "red.html" > < img src = "red.jpeg" alt = "Red" > </ a ></ li >
</ ul > In this example, each button has a set of images to indicate the kind of color output desired by the user. The first image is used in each case to give the alternative text.
< button name = "rgb" > < img src = "red" alt = "RGB" >< img src = "green" alt = "" >< img src = "blue" alt = "" > </ button >
< button name = "cmyk" > < img src = "cyan" alt = "CMYK" >< img src = "magenta" alt = "" >< img src = "yellow" alt = "" >< img src = "black" alt = "" > </ button > Since each image represents one part of the text, it could also be written like this:
< button name = "rgb" > < img src = "red" alt = "R" >< img src = "green" alt = "G" >< img src = "blue" alt = "B" > </ button >
< button name = "cmyk" > < img src = "cyan" alt = "C" >< img src = "magenta" alt = "M" >< img src = "yellow" alt = "Y" >< img src = "black" alt = "K" > </ button > However, with other alternative text, this might not work, and putting all the alternative text into one image in each case might make more sense:
< button name = "rgb" > < img src = "red" alt = "sRGB profile" >< img src = "green" alt = "" >< img src = "blue" alt = "" > </ button >
< button name = "cmyk" > < img src = "cyan" alt = "CMYK profile" >< img src = "magenta" alt = "" >< img src = "yellow" alt = "" >< img src = "black" alt = "" > </ button > Sometimes something can be more clearly stated in graphical form, for example as a flowchart, a
diagram, a graph, or a simple map showing directions. In such cases, an image can be given using
the img element, but the lesser textual version must still be given, so that users
who are unable to view the image (e.g. because they have a very slow connection, or because they
are using a text-only browser, or because they are listening to the page being read out by a
hands-free automobile voice web browser, or simply because they are blind) are still able to
understand the message being conveyed.
The text must be given in the alt attribute, and must convey
the same message as the image specified in the src
attribute.
It is important to realize that the alternative text is a replacement for the image, not a description of the image.
In the following example we have a flowchart
in image form, with text in the alt attribute rephrasing the
flowchart in prose form:
< p > In the common case, the data handled by the tokenization stage
comes from the network, but it can also come from script.</ p >
< p > < img src = "images/parsing-model-overview.svg" alt = "The Network
passes data to the Input Stream Preprocessor, which passes it to the
Tokenizer, which passes it to the Tree Construction stage. From there,
data goes to both the DOM and to Script Execution. Script Execution is
linked to the DOM, and, using document.write(), passes data to the
Tokenizer." > </ p > Here's another example, showing a good solution and a bad solution to the problem of including an image in a description.
First, here's the good solution. This sample shows how the alternative text should just be what you would have put in the prose if the image had never existed.
<!-- This is the correct way to do things. -->
< p >
You are standing in an open field west of a house.
< img src = "house.jpeg" alt = "The house is white, with a boarded front door." >
There is a small mailbox here.
</ p > Second, here's the bad solution. In this incorrect way of doing things, the alternative text is simply a description of the image, instead of a textual replacement for the image. It's bad because when the image isn't shown, the text doesn't flow as well as in the first example.
<!-- This is the wrong way to do things. -->
< p >
You are standing in an open field west of a house.
< img src = "house.jpeg" alt = "A white house, with a boarded front door." >
There is a small mailbox here.
</ p > Text such as "Photo of white house with boarded door" would be equally bad alternative text
(though it could be suitable for the title attribute or in the
figcaption element of a figure with this image).
A document can contain information in iconic form. The icon is intended to help users of visual browsers to recognize features at a glance.
In some cases, the icon is supplemental to a text label conveying the same meaning. In those
cases, the alt attribute must be present but must be empty.
Here the icons are next to text that conveys the same meaning, so they have an empty alt attribute:
< nav >
< p >< a href = "/help/" > < img src = "/icons/help.png" alt = "" > Help</ a ></ p >
< p >< a href = "/configure/" > < img src = "/icons/configuration.png" alt = "" >
Configuration Tools</ a ></ p >
</ nav > In other cases, the icon has no text next to it describing what it means; the icon is supposed
to be self-explanatory. In those cases, an equivalent textual label must be given in the alt attribute.
Here, posts on a news site are labeled with an icon indicating their topic.
< body >
< article >
< header >
< h1 > Ratatouille wins < i > Best Movie of the Year</ i > award</ h1 >
< p > < img src = "movies.png" alt = "Movies" > </ p >
</ header >
< p > Pixar has won yet another < i > Best Movie of the Year</ i > award,
making this its 8th win in the last 12 years.</ p >
</ article >
< article >
< header >
< h1 > Latest TWiT episode is online</ h1 >
< p > < img src = "podcasts.png" alt = "Podcasts" > </ p >
</ header >
< p > The latest TWiT episode has been posted, in which we hear
several tech news stories as well as learning much more about the
iPhone. This week, the panelists compare how reflective their
iPhones' Apple logos are.</ p >
</ article >
</ body > Many pages include logos, insignia, flags, or emblems, which stand for a particular entity such as a company, organization, project, band, software package, country, or some such.
If the logo is being used to represent the entity, e.g. as a page heading, the alt attribute must contain the name of the entity being represented by
the logo. The alt attribute must not contain text like
the word "logo", as it is not the fact that it is a logo that is being conveyed, it's the entity
itself.
If the logo is being used next to the name of the entity that it represents, then the logo is
supplemental, and its alt attribute must instead be empty.
If the logo is merely used as decorative material (as branding, or, for example, as a side image in an article that mentions the entity to which the logo belongs), then the entry below on purely decorative images applies. If the logo is actually being discussed, then it is being used as a phrase or paragraph (the description of the logo) with an alternative graphical representation (the logo itself), and the first entry above applies.
In the following snippets, all four of the above cases are present. First, we see a logo used to represent a company:
< h1 > < img src = "XYZ.gif" alt = "The XYZ company" > </ h1 > Next, we see a paragraph which uses a logo right next to the company name, and so doesn't have any alternative text:
< article >
< h2 > News</ h2 >
< p > We have recently been looking at buying the < img src = "alpha.gif"
alt = "" > ΑΒΓ company, a small Greek company
specializing in our type of product.</ p > In this third snippet, we have a logo being used in an aside, as part of the larger article discussing the acquisition:
< aside >< p >< img src = "alpha-large.gif" alt = "" ></ p ></ aside >
< p > The ΑΒΓ company has had a good quarter, and our
pie chart studies of their accounts suggest a much bigger blue slice
than its green and orange slices, which is always a good sign.</ p >
</ article > Finally, we have an opinion piece talking about a logo, and the logo is therefore described in detail in the alternative text.
< p > Consider for a moment their logo:</ p >
< p >< img src = "/images/logo" alt = "It consists of a green circle with a
green question mark centered inside it." ></ p >
< p > How unoriginal can you get? I mean, oooooh, a question mark, how
< em > revolutionary</ em > , how utterly < em > ground-breaking</ em > , I'm
sure everyone will rush to adopt those specifications now! They could
at least have tried for some sort of, I don't know, sequence of
rounded squares with varying shades of green and bold white outlines,
at least that would look good on the cover of a blue book.</ p > This example shows how the alternative text should be written such that if the image isn't available, and the text is used instead, the text flows seamlessly into the surrounding text, as if the image had never been there in the first place.
Sometimes, an image just consists of text, and the purpose of the image is not to highlight the actual typographic effects used to render the text, but just to convey the text itself.
In such cases, the alt attribute must be present but must
consist of the same text as written in the image itself.
Consider a graphic containing the text "Earth Day", but with the letters all decorated with flowers and plants. If the text is merely being used as a heading, to spice up the page for graphical users, then the correct alternative text is just the same text "Earth Day", and no mention need be made of the decorations:
< h1 > < img src = "earthdayheading.png" alt = "Earth Day" > </ h1 > An illuminated manuscript might use graphics for some of its images. The alternative text in such a situation is just the character that the image represents.
< p >< img src = "initials/o.svg" alt = "O" > nce upon a time and a long long time ago, late at
night, when it was dark, over the hills, through the woods, across a great ocean, in a land far
away, in a small house, on a hill, under a full moon...When an image is used to represent a character that cannot otherwise be represented in Unicode, for example gaiji, itaiji, or new characters such as novel currency symbols, the alternative text should be a more conventional way of writing the same thing, e.g. using the phonetic hiragana or katakana to give the character's pronunciation.
In this example from 1997, a new-fangled currency symbol that looks like a curly E with two bars in the middle instead of one is represented using an image. The alternative text gives the character's pronunciation.
< p > Only < img src = "euro.png" alt = "euro " > 5.99!An image should not be used if characters would serve an identical purpose. Only when the text cannot be directly represented using text, e.g., because of decorations or because there is no appropriate character (as in the case of gaiji), would an image be appropriate.
If an author is tempted to use an image because their default system font does not support a given character, then web fonts are a better solution than images.
In many cases, the image is actually just supplementary, and its presence merely reinforces the
surrounding text. In these cases, the alt attribute must be
present but its value must be the empty string.
In general, an image falls into this category if removing the image doesn't make the page any less useful, but including the image makes it a lot easier for users of visual browsers to understand the concept.
A flowchart that repeats the previous paragraph in graphical form:
< p > The Network passes data to the Input Stream Preprocessor, which
passes it to the Tokenizer, which passes it to the Tree Construction
stage. From there, data goes to both the DOM and to Script Execution.
Script Execution is linked to the DOM, and, using document.write(),
passes data to the Tokenizer.</ p >
< p >< img src = "images/parsing-model-overview.svg" alt = "" ></ p > In these cases, it would be wrong to include alternative text that consists of just a caption.
If a caption is to be included, then either the title attribute
can be used, or the figure and figcaption elements can be used. In the
latter case, the image would in fact be a phrase or paragraph with an alternative graphical
representation, and would thus require alternative text.
<!-- Using the title="" attribute -->
< p > The Network passes data to the Input Stream Preprocessor, which
passes it to the Tokenizer, which passes it to the Tree Construction
stage. From there, data goes to both the DOM and to Script Execution.
Script Execution is linked to the DOM, and, using document.write(),
passes data to the Tokenizer.</ p >
< p > < img src = "images/parsing-model-overview.svg" alt = ""
title = "Flowchart representation of the parsing model." > </ p > <!-- Using <figure> and <figcaption> -->
< p > The Network passes data to the Input Stream Preprocessor, which
passes it to the Tokenizer, which passes it to the Tree Construction
stage. From there, data goes to both the DOM and to Script Execution.
Script Execution is linked to the DOM, and, using document.write(),
passes data to the Tokenizer.</ p >
< figure >
< img src = "images/parsing-model-overview.svg" alt = "The Network leads to
the Input Stream Preprocessor, which leads to the Tokenizer, which
leads to the Tree Construction stage. The Tree Construction stage
leads to two items. The first is Script Execution, which leads via
document.write() back to the Tokenizer. The second item from which
Tree Construction leads is the DOM. The DOM is related to the Script
Execution." >
< figcaption > Flowchart representation of the parsing model.</ figcaption >
</ figure > <!-- This is WRONG. Do not do this. Instead, do what the above examples do. -->
< p > The Network passes data to the Input Stream Preprocessor, which
passes it to the Tokenizer, which passes it to the Tree Construction
stage. From there, data goes to both the DOM and to Script Execution.
Script Execution is linked to the DOM, and, using document.write(),
passes data to the Tokenizer.</ p >
< p >< img src = "images/parsing-model-overview.svg"
alt = "Flowchart representation of the parsing model." ></ p >
<!-- Never put the image's caption in the alt="" attribute! --> A graph that repeats the previous paragraph in graphical form:
< p > According to a study covering several billion pages,
about 62% of documents on the web in 2007 triggered the Quirks
rendering mode of web browsers, about 30% triggered the Almost
Standards mode, and about 9% triggered the Standards mode.</ p >
< p >< img src = "rendering-mode-pie-chart.png" alt = "" ></ p > Sometimes, an image is not critical to the content, but is nonetheless neither purely
decorative nor entirely redundant with the text. In these cases, the alt attribute must be present, and its value should either be the
empty string, or a textual representation of the information that the image conveys. If the image
has a caption giving the image's title, then the alt
attribute's value must not be empty (as that would be quite confusing for non-visual readers).
Consider a news article about a political figure, in which the individual's face was shown in an image. The image is not purely decorative, as it is relevant to the story. The image is not entirely redundant with the story either, as it shows what the politician looks like. Whether any alternative text need be provided is an authoring decision, decided by whether the image influences the interpretation of the prose.
In this first variant, the image is shown without context, and no alternative text is provided:
< p > < img src = "president.jpeg" alt = "" > Ahead of today's referendum,
the President wrote an open letter to all registered voters. In it, she admitted that the country was
divided.</ p > If the picture is just a face, there might be no value in describing it. It's of no interest to the reader whether the individual has red hair or blond hair, whether the individual has white skin or black skin, whether the individual has one eye or two eyes.
However, if the picture is more dynamic, for instance showing the politician as angry, or particularly happy, or devastated, some alternative text would be useful in setting the tone of the article, a tone that might otherwise be missed:
< p > < img src = "president.jpeg" alt = "The President is sad." >
Ahead of today's referendum, the President wrote an open letter to all
registered voters. In it, she admitted that the country was divided.
</ p > < p > < img src = "president.jpeg" alt = "The President is happy!" >
Ahead of today's referendum, the President wrote an open letter to all
registered voters. In it, she admitted that the country was divided.
</ p > Whether the individual was "sad" or "happy" makes a difference to how the rest of the paragraph is to be interpreted: is she likely saying that she is unhappy with the country being divided, or is she saying that the prospect of a divided country is good for her political career? The interpretation varies based on the image.
If the image has a caption, then including alternative text avoids leaving the non-visual user confused as to what the caption refers to.
< p > Ahead of today's referendum, the President wrote an open letter to
all registered voters. In it, she admitted that the country was divided.</ p >
< figure >
< img src = "president.jpeg"
alt = "A high forehead, cheerful disposition, and dark hair round out the President's face." >
< figcaption > The President of Ruritania. Photo © 2014 PolitiPhoto. </ figcaption >
</ figure > If an image is decorative but isn't especially page-specific — for example an image that forms part of a site-wide design scheme — the image should be specified in the site's CSS, not in the markup of the document.
However, a decorative image that isn't discussed by the surrounding text but still has some
relevance can be included in a page using the img element. Such images are
decorative, but still form part of the content. In these cases, the alt attribute must be present but its value must be the empty
string.
Examples where the image is purely decorative despite being relevant would include things like a photo of the Black Rock City landscape in a blog post about an event at Burning Man, or an image of a painting inspired by a poem, on a page reciting that poem. The following snippet shows an example of the latter case (only the first verse is included in this snippet):
< h1 > The Lady of Shalott</ h1 >
< p >< img src = "shalott.jpeg" alt = "" ></ p >
< p > On either side the river lie< br >
Long fields of barley and of rye,< br >
That clothe the wold and meet the sky;< br >
And through the field the road run by< br >
To many-tower'd Camelot;< br >
And up and down the people go,< br >
Gazing where the lilies blow< br >
Round an island there below,< br >
The island of Shalott.</ p > When a picture has been sliced into smaller image files that are then displayed together to
form the complete picture again, one of the images must have its alt attribute set as per the relevant rules that would be appropriate
for the picture as a whole, and then all the remaining images must have their alt attribute set to the empty string.
In the following example, a picture representing a company logo for XYZ Corp has been split into two pieces, the first containing the letters "XYZ" and the second with the word "Corp". The alternative text ("XYZ Corp") is all in the first image.
< h1 > < img src = "logo1.png" alt = "XYZ Corp" >< img src = "logo2.png" alt = "" > </ h1 > In the following example, a rating is shown as three filled stars and two empty stars. While the alternative text could have been "★★★☆☆", the author has instead decided to more helpfully give the rating in the form "3 out of 5". That is the alternative text of the first image, and the rest have blank alternative text.
< p > Rating: < meter max = 5 value = 3 > < img src = "1" alt = "3 out of 5"
>< img src = "1" alt = "" >< img src = "1" alt = "" >< img src = "0" alt = ""
>< img src = "0" alt = "" > </ meter ></ p > Generally, image maps should be used instead of slicing an image for links.
However, if an image is indeed sliced and any of the components of the sliced picture are the
sole contents of links, then one image per link must have alternative text in its alt attribute representing the purpose of the link.
In the following example, a picture representing the flying spaghetti monster emblem, with each of the left noodly appendages and the right noodly appendages in different images, so that the user can pick the left side or the right side in an adventure.
< h1 > The Church</ h1 >
< p > You come across a flying spaghetti monster. Which side of His
Noodliness do you wish to reach out for?</ p >
< p >< a href = "?go=left" >< img src = "fsm-left.png" alt = "Left side. " ></ a
>< img src = "fsm-middle.png" alt = ""
>< a href = "?go=right" >< img src = "fsm-right.png" alt = "Right side." ></ a ></ p > In some cases, the image is a critical part of the content. This could be the case, for instance, on a page that is part of a photo gallery. The image is the whole point of the page containing it.
How to provide alternative text for an image that is a key part of the content depends on the image's provenance.
When it is possible for detailed alternative text to be provided, for example if the image is
part of a series of screenshots in a magazine review, or part of a comic strip, or is a
photograph in a blog entry about that photograph, text that can serve as a substitute for the
image must be given as the contents of the alt attribute.
A screenshot in a gallery of screenshots for a new OS, with some alternative text:
< figure >
< img src = "KDE%20Light%20desktop.png"
alt = "The desktop is blue, with icons along the left hand side in
two columns, reading System, Home, K-Mail, etc. A window is
open showing that menus wrap to a second line if they
cannot fit in the window. The window has a list of icons
along the top, with an address bar below it, a list of
icons for tabs along the left edge, a status bar on the
bottom, and two panes in the middle. The desktop has a bar
at the bottom of the screen with a few buttons, a pager, a
list of open applications, and a clock." >
< figcaption > Screenshot of a KDE desktop.</ figcaption >
</ figure > A graph in a financial report:
< img src = "sales.gif"
title = "Sales graph"
alt = "From 1998 to 2005, sales increased by the following percentages
with each year: 624%, 75%, 138%, 40%, 35%, 9%, 21%" > Note that "sales graph" would be inadequate alternative text for a sales graph. Text that would be a good caption is not generally suitable as replacement text.
In certain cases, the nature of the image might be such that providing thorough alternative text is impractical. For example, the image could be indistinct, or could be a complex fractal, or could be a detailed topographical map.
In these cases, the alt attribute must contain some
suitable alternative text, but it may be somewhat brief.
Sometimes there simply is no text that can do justice to an image. For example, there is little that can be said to usefully describe a Rorschach inkblot test. However, a description, even if brief, is still better than nothing:
< figure >
< img src = "/commons/a/a7/Rorschach1.jpg" alt = "A shape with left-right
symmetry with indistinct edges, with a small gap in the center, two
larger gaps offset slightly from the center, with two similar gaps
under them. The outline is wider in the top half than the bottom
half, with the sides extending upwards higher than the center, and
the center extending below the sides." >
< figcaption > A black outline of the first of the ten cards
in the Rorschach inkblot test.</ figcaption >
</ figure > Note that the following would be a very bad use of alternative text:
<!-- This example is wrong. Do not copy it. -->
< figure >
< img src = "/commons/a/a7/Rorschach1.jpg" alt = "A black outline
of the first of the ten cards in the Rorschach inkblot test." >
< figcaption > A black outline of the first of the ten cards
in the Rorschach inkblot test.</ figcaption >
</ figure > Including the caption in the alternative text like this isn't useful because it effectively duplicates the caption for users who don't have images, taunting them twice yet not helping them any more than if they had only read or heard the caption once.
Another example of an image that defies full description is a fractal, which, by definition, is infinite in detail.
The following example shows one possible way of providing alternative text for the full view of an image of the Mandelbrot set.
< img src = "ms1.jpeg" alt = "The Mandelbrot set appears as a cardioid with
its cusp on the real axis in the positive direction, with a smaller
bulb aligned along the same center line, touching it in the negative
direction, and with these two shapes being surrounded by smaller bulbs
of various sizes." > Similarly, a photograph of a person's face, for example in a biography, can be considered quite relevant and key to the content, but it can be hard to fully substitute text for:
< section class = "bio" >
< h1 > A Biography of Isaac Asimov</ h1 >
< p > Born < b > Isaak Yudovich Ozimov</ b > in 1920, Isaac was a prolific author.</ p >
< p >< img src = "headpics/asimov.jpeg" alt = "Isaac Asimov had dark hair, a tall forehead, and wore glasses.
Later in life, he wore long white sideburns." ></ p >
< p > Asimov was born in Russia, and moved to the US when he was three years old.</ p >
< p > ...</ p >
</ section > In such cases it is unnecessary (and indeed discouraged) to include a reference to the presence of the image itself in the alternative text, since such text would be redundant with the browser itself reporting the presence of the image. For example, if the alternative text was "A photo of Isaac Asimov", then a conforming user agent might read that out as "(Image) A photo of Isaac Asimov" rather than the more useful "(Image) Isaac Asimov had dark hair, a tall forehead, and wore glasses...".
In some unfortunate cases, there might be no alternative text available at all, either because the image is obtained in some automated fashion without any associated alternative text (e.g., a webcam), or because the page is being generated by a script using user-provided images where the user did not provide suitable or usable alternative text (e.g. photograph sharing sites), or because the author does not themself know what the images represent (e.g. a blind photographer sharing an image on their blog).
In such cases, the alt attribute may be omitted, but one of
the following conditions must be met as well:
The img element is in a
figure element that contains a figcaption element that contains
content other than inter-element whitespace, and, ignoring the
figcaption element and its descendants, the figure element has no
flow content descendants other than inter-element whitespace and the
img element.
The title attribute is present and has a non-empty
value.
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).
Such cases are to be kept to an absolute minimum. If there is even the slightest
possibility of the author having the ability to provide real alternative text, then it would not
be acceptable to omit the alt attribute.
A photo on a photo-sharing site, if the site received the image with no metadata other than the caption, could be marked up as follows:
< figure >
< img src = "1100670787_6a7c664aef.jpg" >
< figcaption > Bubbles traveled everywhere with us.</ figcaption >
</ figure > It would be better, however, if a detailed description of the important parts of the image obtained from the user and included on the page.
A blind user's blog in which a photo taken by the user is shown. Initially, the user might not have any idea what the photo they took shows:
< article >
< h1 > I took a photo</ h1 >
< p > I went out today and took a photo!</ p >
< figure >
< img src = "photo2.jpeg" >
< figcaption > A photograph taken blindly from my front porch.</ figcaption >
</ figure >
</ article > Eventually though, the user might obtain a description of the image from their friends and could then include alternative text:
< article >
< h1 > I took a photo</ h1 >
< p > I went out today and took a photo!</ p >
< figure >
< img src = "photo2.jpeg" alt = "The photograph shows my squirrel
feeder hanging from the edge of my roof. It is half full, but there
are no squirrels around. In the background, out-of-focus trees fill the
shot. The feeder is made of wood with a metal grate, and it contains
peanuts. The edge of the roof is wooden too, and is painted white
with light blue streaks." >
< figcaption > A photograph taken blindly from my front porch.</ figcaption >
</ figure >
</ article > Sometimes the entire point of the image is that a textual description is not available, and
the user is to provide the description. For instance, the point of a CAPTCHA image is to see if
the user can literally read the graphic. Here is one way to mark up a CAPTCHA (note the title attribute):
< p >< label > What does this image say?
< img src = "captcha.cgi?id=8934" title = "CAPTCHA" >
< input type = text name = captcha ></ label >
(If you cannot see the image, you can use an < a
href = "?audio" > audio</ a > test instead.)</ p > Another example would be software that displays images and asks for alternative text precisely for the purpose of then writing a page with correct alternative text. Such a page could have a table of images, like this:
< table >
< thead >
< tr > < th > Image < th > Description
< tbody >
< tr >
< td > < img src = "2421.png" title = "Image 640 by 100, filename 'banner.gif'" >
< td > < input name = "alt2421" >
< tr >
< td > < img src = "2422.png" title = "Image 200 by 480, filename 'ad3.gif'" >
< td > < input name = "alt2422" >
</ table > Notice that even in this example, as much useful information as possible is still included
in the title attribute.
Since some users cannot use images at all (e.g. because they have a very slow
connection, or because they are using a text-only browser, or because they are listening to the
page being read out by a hands-free automobile voice web browser, or simply because they are
blind), the alt attribute is only allowed to be omitted rather
than being provided with replacement text when no alternative text is available and none can be
made available, as in the above examples. Lack of effort from the part of the author is not an
acceptable reason for omitting the alt attribute.
Generally authors should avoid using img elements for purposes other than showing
images.
If an img element is being used for purposes other than showing an image, e.g. as
part of a service to count page views, then the alt attribute
must be the empty string.
In such cases, the width and height attributes should both be set to zero.
This section does not apply to documents that are publicly accessible, or whose target audience is not necessarily personally known to the author, such as documents on a web site, emails sent to public mailing lists, or software documentation.
When an image is included in a private communication (such as an HTML email) aimed at a
specific person who is known to be able to view images, the alt
attribute may be omitted. However, even in such cases authors are strongly urged to include
alternative text (as appropriate according to the kind of image involved, as described in the
above entries), so that the email is still usable should the user use a mail client that does not
support images, or should the document be forwarded on to other users whose abilities might not
include easily seeing images.
Markup generators (such as WYSIWYG authoring tools) should, wherever possible, obtain alternative text from their users. However, it is recognized that in many cases, this will not be possible.
For images that are the sole contents of links, markup generators should examine the link target to determine the title of the target, or the URL of the target, and use information obtained in this manner as the alternative text.
For images that have captions, markup generators should use the figure and
figcaption elements, or the title attribute, to
provide the image's caption.
As a last resort, implementers should either set the alt
attribute to the empty string, under the assumption that the image is a purely decorative image
that doesn't add any information but is still specific to the surrounding content, or omit the
alt attribute altogether, under the assumption that the image is
a key part of the content.
Markup generators may specify a generator-unable-to-provide-required-alt
attribute on img elements for which they have been unable to obtain alternative text
and for which they have therefore omitted the alt attribute. The
value of this attribute must be the empty string. Documents containing such attributes are not
conforming, but conformance checkers will silently
ignore this error.
This is intended to avoid markup generators from being pressured into replacing
the error of omitting the alt attribute with the even more
egregious error of providing phony alternative text, because state-of-the-art automated
conformance checkers cannot distinguish phony alternative text from correct alternative text.
Markup generators should generally avoid using the image's own filename as the alternative text. Similarly, markup generators should avoid generating alternative text from any content that will be equally available to presentation user agents (e.g., web browsers).
This is because once a page is generated, it will typically not be updated, whereas the browsers that later read the page can be updated by the user, therefore the browser is likely to have more up-to-date and finely-tuned heuristics than the markup generator did when generating the page.
A conformance checker must report the lack of an alt
attribute as an error unless one of the conditions listed below applies:
The img element is in a figure element that satisfies the conditions described above.
The img element has a title attribute with a
value that is not the empty string (also as described
above).
The conformance checker has been configured to assume that the document is an email or document intended for a specific person who is known to be able to view images.
The img element has a (non-conforming) generator-unable-to-provide-required-alt
attribute whose value is the empty string. A conformance checker that is not reporting the lack
of an alt attribute as an error must also not report the
presence of the empty generator-unable-to-provide-required-alt
attribute as an error. (This case does not represent a case where the document is conforming,
only that the generator could not determine appropriate alternative text — validators are
not required to show an error in this case, because such an error might encourage markup
generators to include bogus alternative text purely in an attempt to silence validators.
Naturally, conformance checkers may report the lack of an alt attribute as an error even in the presence of the generator-unable-to-provide-required-alt
attribute; for example, there could be a user option to report all conformance errors
even those that might be the more or less inevitable result of using a markup
generator.)
iframe 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.
src — Address of the resource
srcdoc — A document to render in the iframe
name — Name of content navigable
sandbox — Security rules for nested content
allow — Permissions policy to be applied to the iframe's contents
allowfullscreen — Whether to allow the iframe's contents to use requestFullscreen()
width — Horizontal dimension
height — Vertical dimension
referrerpolicy — Referrer policy for fetches initiated by the element
loading — Used when determining loading deferral
[Exposed =Window ]
interface HTMLIFrameElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions , ReflectURL ] attribute USVString src ;
[CEReactions ] attribute (TrustedHTML or DOMString ) srcdoc ;
[CEReactions , Reflect ] attribute DOMString name ;
[SameObject , PutForwards =value , Reflect ] readonly attribute DOMTokenList sandbox ;
[CEReactions , Reflect ] attribute DOMString allow ;
[CEReactions , Reflect ] attribute boolean allowFullscreen ;
[CEReactions , Reflect ] attribute DOMString width ;
[CEReactions , Reflect ] attribute DOMString height ;
[CEReactions ] attribute DOMString referrerPolicy ;
[CEReactions ] attribute DOMString loading ;
readonly attribute Document ? contentDocument ;
readonly attribute WindowProxy ? contentWindow ;
Document ? getSVGDocument ();
// also has obsolete members
};The iframe element represents its content navigable.
The src attribute
gives the URL of a page that the element's content navigable is to
contain. The attribute, if present, must be a valid non-empty URL potentially surrounded by
spaces. If the itemprop attribute is specified on an
iframe element, then the src attribute must
also be specified.
Support in all current engines.
The srcdoc
attribute gives the content of the page that the element's content navigable is to
contain. The value of the attribute is used to construct an iframe srcdoc document, which is a Document whose
URL matches about:srcdoc.
The srcdoc attribute, if present, must have a value
using the HTML syntax that consists of the following syntactic components, in the
given order:
html element.The above requirements apply in XML documents as well.
Here a blog uses the srcdoc attribute in conjunction
with the sandbox attribute described below to provide
users of user agents that support this feature with an extra layer of protection from script
injection in the blog post comments:
< article >
< h1 > I got my own magazine!</ h1 >
< p > After much effort, I've finally found a publisher, and so now I
have my own magazine! Isn't that awesome?! The first issue will come
out in September, and we have articles about getting food, and about
getting in boxes, it's going to be great!</ p >
< footer >
< p > Written by < a href = "/users/cap" > cap</ a > , 1 hour ago.
</ footer >
< article >
< footer > Thirteen minutes ago, < a href = "/users/ch" > ch</ a > wrote: </ footer >
< iframe sandbox srcdoc = "<p>did you get a cover picture yet?" ></ iframe >
</ article >
< article >
< footer > Nine minutes ago, < a href = "/users/cap" > cap</ a > wrote: </ footer >
< iframe sandbox srcdoc = "<p>Yeah, you can see it <a href="/gallery?mode=cover&amp;page=1">in my gallery</a>." ></ iframe >
</ article >
< article >
< footer > Five minutes ago, < a href = "/users/ch" > ch</ a > wrote: </ footer >
< iframe sandbox srcdoc = "<p>hey that's earl's table.
<p>you should get earl&amp;me on the next cover." ></ iframe >
</ article > Notice the way that quotes have to be escaped (otherwise the srcdoc attribute would end prematurely), and the way raw
ampersands (e.g. in URLs or in prose) mentioned in the sandboxed content have to be
doubly escaped — once so that the ampersand is preserved when originally parsing
the srcdoc attribute, and once more to prevent the
ampersand from being misinterpreted when parsing the sandboxed content.
Furthermore, notice that since the DOCTYPE is optional in
iframe srcdoc documents, and the html,
head, and body elements have optional
start and end tags, and the title element is also optional in iframe srcdoc
documents, the markup in a srcdoc attribute can be
relatively succinct despite representing an entire document, since only the contents of the
body element need appear literally in the syntax. The other elements are still
present, but only by implication.
In the HTML syntax, authors need only remember to use U+0022
QUOTATION MARK characters (") to wrap the attribute contents and then to escape all U+0026
AMPERSAND (&) and U+0022 QUOTATION MARK (") characters, and to specify the sandbox attribute, to ensure safe embedding of content. (And
remember to escape ampersands before quotation marks, to ensure quotation marks become "
and not &quot;.)
In XML the U+003C LESS-THAN SIGN character (<) needs to be escaped as well. In order to prevent attribute-value normalization, some of XML's whitespace characters — specifically U+0009 CHARACTER TABULATION (tab), U+000A LINE FEED (LF), and U+000D CARRIAGE RETURN (CR) — also need to be escaped. [XML]
If the src attribute and the srcdoc attribute are both specified together, the srcdoc attribute takes priority. This allows authors to provide
a fallback URL for legacy user agents that do not support the srcdoc attribute.
The iframe HTML element post-connection steps, given
insertedNode, are:
Create a new child navigable for insertedNode.
If insertedNode has a sandbox
attribute, then parse the sandboxing
directive given the attribute's value and insertedNode's
iframe sandboxing flag set.
Process the iframe attributes for insertedNode, with
initialInsertion set to true.
The iframe HTML element removing steps, given
removedNode, are to destroy a child navigable given
removedNode.
This happens without any unload events firing
(the element's content document is destroyed, not unloaded).
Although iframes are processed while in a shadow tree,
per the above, several other aspects of their behavior are not well-defined with regards to
shadow trees. See issue #763 for more
detail.
Whenever an iframe element with a non-null content navigable has its
srcdoc attribute set, changed, or removed, the user
agent must process the iframe attributes.
Similarly, whenever an iframe element with a non-null content
navigable but with no srcdoc attribute specified
has its src attribute set, changed, or removed, the user
agent must process the iframe attributes.
To process the iframe attributes for an element element,
with an optional boolean initialInsertion (default false):
If element's srcdoc attribute is
specified, then:
Set element's current navigation was lazy loaded boolean to false.
If the will lazy load element steps given element return true, then:
Set element's lazy load resumption steps to the rest of this algorithm starting with the step labeled navigate to the srcdoc resource.
Set element's current navigation was lazy loaded boolean to true.
Start intersection-observing a lazy loading element for element.
Return.
Navigate to the srcdoc resource: Navigate an iframe or
frame given element, about:srcdoc, the empty
string, and the value of element's srcdoc
attribute.
The resulting Document must be considered an iframe srcdoc document.
Otherwise:
Let url be the result of running the shared attribute processing steps
for iframe and frame elements given element and
initialInsertion.
If url is null, then return.
If url matches about:blank and
initialInsertion is true, then:
Run the iframe load event steps given element.
Return.
Let referrerPolicy be the current state of element's referrerpolicy content attribute.
Set element's current navigation was lazy loaded boolean to false.
If the will lazy load element steps given element return true, then:
Set element's lazy load resumption steps to the rest of this algorithm starting with the step labeled navigate.
Set element's current navigation was lazy loaded boolean to true.
Start intersection-observing a lazy loading element for element.
Return.
Navigate: Navigate an iframe or frame
given element, url, and referrerPolicy.
The shared attribute processing steps
for iframe and frame elements, given an element
element and a boolean initialInsertion, are:
Let url be the URL record about:blank.
If element has a src attribute specified,
and its value is not the empty string, then:
Let maybeURL be the result of encoding-parsing a URL given that attribute's value, relative to element's node document.
If maybeURL is not failure, then set url to maybeURL.
If the inclusive ancestor navigables of element's node navigable contains a navigable whose active document's URL equals url with exclude fragments set to true, then return null.
If url matches about:blank and
initialInsertion is true, then perform the URL and history update steps
given element's content navigable's active
document and url.
This is necessary in case url is something like about:blank?foo. If url is just plain about:blank, this will do nothing.
Return url.
To navigate an iframe or frame given an element
element, a URL url, a referrer policy
referrerPolicy, an optional string-or-null srcdocString (default
null), and an optional boolean initialInsertion (default false):
Let historyHandling be "auto".
If element's content navigable's active document is not completely loaded, then set
historyHandling to "replace".
If element is an iframe, then set element's pending resource-timing start time to
the current high resolution time given element's
node document's relevant global object.
Navigate element's content navigable to url using element's node document, with historyHandling set to historyHandling, referrerPolicy set to referrerPolicy, documentResource set to srcdocString, and initialInsertion set to initialInsertion.
Each Document has an iframe load in progress flag and a mute
iframe load flag. When a Document is created, these flags must be unset for
that Document.
To run the iframe load event steps, given an iframe element
element:
Assert: element's content navigable is not null.
Let childDocument be element's content navigable's active document.
If childDocument has its mute iframe load flag set, then return.
If element's pending resource-timing start time is not null, then:
Let global be element's node document's relevant global object.
Let fallbackTimingInfo be a new fetch timing info whose start time is element's pending resource-timing start time and whose response end time is the current high resolution time given global.
Mark resource timing given fallbackTimingInfo, url,
"iframe", global, the empty string, a new
response body info, and 0.
Set element's pending resource-timing start time to null.
Set childDocument's iframe load in progress flag.
Fire an event named load at element.
Unset childDocument's iframe load in progress flag.
This, in conjunction with scripting, can be used to probe the URL space of the local network's HTTP servers. User agents may implement cross-origin access control policies that are stricter than those described above to mitigate this attack, but unfortunately such policies are typically not compatible with existing web content.
If an element type potentially delays the load event, then for each element element of that type, the user agent must delay the load event of element's node document if element's content navigable is non-null and any of the following are true:
element's content navigable's active document is not ready for post-load tasks;
element's content navigable's is delaying load events is true; or
anything is delaying the load event of element's content navigable's active document.
If, during the handling of the load event,
element's content navigable is again navigated, that will further delay the load event.
Each iframe element has an associated current navigation was lazy
loaded boolean, initially false. It is set and unset in the process the
iframe attributes algorithm.
An iframe element whose current navigation was lazy loaded boolean is
false potentially delays the load event.
Each iframe element has an associated null or
DOMHighResTimeStamp pending resource-timing start time,
initially set to null.
If, when the element is created, the srcdoc attribute is not set, and the src attribute is either also not set or set but its value cannot
be parsed, the element's content
navigable will remain at the initial
about:blank Document.
If the user navigates away from this page, the
iframe's content navigable's active
WindowProxy object will proxy new Window objects for new
Document objects, but the src attribute will
not change.
The name
attribute, if present, must be a valid navigable target name. The given value is
used to name the element's content navigable if present when that is created.
Support in all current engines.
The sandbox
attribute, when specified, enables a set of extra restrictions on any content hosted by the
iframe. Its value must be an unordered set of unique space-separated
tokens that are ASCII case-insensitive. The allowed values are:
allow-downloadsallow-formsallow-modalsallow-orientation-lockallow-pointer-lockallow-popupsallow-popups-to-escape-sandboxallow-presentationallow-same-originallow-scriptsallow-top-navigationallow-top-navigation-by-user-activationallow-top-navigation-to-custom-protocolsWhen the attribute is set, the content is treated as being from a unique opaque origin, forms, scripts, and various potentially
annoying APIs are disabled, and links are prevented from targeting other navigables. The allow-same-origin keyword causes the
content to be treated as being from its real origin instead of forcing it into an opaque origin; the allow-top-navigation keyword allows the
content to navigate its traversable navigable;
the allow-top-navigation-by-user-activation
keyword behaves similarly but allows such navigation only when the
browsing context's active window has transient
activation; the allow-top-navigation-to-custom-protocols
reenables navigations toward non fetch scheme to be handed off to external software; and the allow-forms, allow-modals, allow-orientation-lock, allow-pointer-lock, allow-popups, allow-presentation, allow-scripts, and allow-popups-to-escape-sandbox
keywords re-enable forms, modal dialogs, screen orientation lock, the pointer lock API, popups,
the presentation API, scripts, and the creation of unsandboxed auxiliary browsing contexts respectively. The allow-downloads keyword allows content to
perform downloads. [POINTERLOCK] [SCREENORIENTATION] [PRESENTATION]
The allow-top-navigation and allow-top-navigation-by-user-activation
keywords must not both be specified, as doing so is redundant; only allow-top-navigation will have an effect
in such non-conformant markup.
Similarly, the allow-top-navigation-to-custom-protocols
keyword must not be specified if either allow-top-navigation or allow-popups are specified, as doing so is
redundant.
To allow alert(), confirm(), and prompt() inside
sandboxed content, both the allow-modals
and allow-same-origin keywords need to
be specified, and the loaded URL needs to be same origin with the top-level
origin. Without the allow-same-origin keyword, the content is
always treated as cross-origin, and cross-origin content cannot show simple
dialogs.
Setting both the allow-scripts and allow-same-origin keywords together when the
embedded page has the same origin as the page containing the iframe
allows the embedded page to simply remove the sandbox
attribute and then reload itself, effectively breaking out of the sandbox altogether.
These flags only take effect when the content navigable of the
iframe element is navigated. Removing them, or
removing the entire sandbox attribute, has no effect on
an already-loaded page.
Potentially hostile files should not be served from the same server as the file
containing the iframe element. Sandboxing hostile content is of minimal help if an
attacker can convince the user to just visit the hostile content directly, rather than in the
iframe. To limit the damage that can be caused by hostile HTML content, it should be
served from a separate dedicated domain. Using a different domain ensures that scripts in the
files are unable to attack the site, even if the user is tricked into visiting those pages
directly, without the protection of the sandbox
attribute.
When an iframe element's sandbox
attribute is set or changed while it has a non-null content navigable, the user
agent must parse the sandboxing directive
given the attribute's value and the iframe element's iframe
sandboxing flag set.
When an iframe element's sandbox
attribute is removed while it has a non-null content navigable, the user agent must
empty the iframe element's iframe sandboxing flag set.
In this example, some completely-unknown, potentially hostile, user-provided HTML content is embedded in a page. Because it is served from a separate domain, it is affected by all the normal cross-site restrictions. In addition, the embedded page has scripting disabled, plugins disabled, forms disabled, and it cannot navigate any frames or windows other than itself (or any frames or windows it itself embeds).
< p > We're not scared of you! Here is your content, unedited:</ p >
< iframe sandbox src = "https://usercontent.example.net/getusercontent.cgi?id=12193" ></ iframe > It is important to use a separate domain so that if the attacker convinces the user to visit that page directly, the page doesn't run in the context of the site's origin, which would make the user vulnerable to any attack found in the page.
In this example, a gadget from another site is embedded. The gadget has scripting and forms enabled, and the origin sandbox restrictions are lifted, allowing the gadget to communicate with its originating server. The sandbox is still useful, however, as it disables plugins and popups, thus reducing the risk of the user being exposed to malware and other annoyances.
< iframe sandbox = "allow-same-origin allow-forms allow-scripts"
src = "https://maps.example.com/embedded.html" ></ iframe > Suppose a file A contained the following fragment:
< iframe sandbox = "allow-same-origin allow-forms" src = B ></ iframe > Suppose that file B contained an iframe also:
< iframe sandbox = "allow-scripts" src = C ></ iframe > Further, suppose that file C contained a link:
< a href = D > Link</ a > For this example, suppose all the files were served as text/html.
Page C in this scenario has all the sandboxing flags set. Scripts are disabled, because the
iframe in A has scripts disabled, and this overrides the allow-scripts keyword set on the
iframe in B. Forms are also disabled, because the inner iframe (in B)
does not have the allow-forms keyword
set.
Suppose now that a script in A removes all the sandbox attributes in A and B.
This would change nothing immediately. If the user clicked the link in C, loading page D into
the iframe in B, page D would now act as if the iframe in B had the
allow-same-origin and allow-forms keywords set, because that was the
state of the content navigable in the iframe in A when page B was
loaded.
Generally speaking, dynamically removing or changing the sandbox attribute is ill-advised, because it can make it quite
hard to reason about what will be allowed and what will not.
The allow
attribute, when specified, determines the container
policy that will be used when the permissions policy for a
Document in the iframe's content navigable is initialized.
Its value must be a serialized permissions
policy. [PERMISSIONSPOLICY]
In this example, an iframe is used to embed a map from an online navigation
service. The allow attribute is used to enable the
Geolocation API within the nested context.
< iframe src = "https://maps.example.com/" allow = "geolocation" ></ iframe > The allowfullscreen attribute is a boolean
attribute. When specified, it indicates that Document objects in the
iframe element's content navigable will be initialized with a permissions policy which allows the "fullscreen" feature to be used from any origin. This is enforced by
the process permissions policy
attributes algorithm. [PERMISSIONSPOLICY]
Here, an iframe is used to embed a player from a video site. The allowfullscreen attribute is needed to enable the
player to show its video fullscreen.
< article >
< header >
< p >< img src = "/usericons/1627591962735" > < b > Fred Flintstone</ b ></ p >
< p >< a href = "/posts/3095182851" rel = bookmark > 12:44</ a > — < a href = "#acl-3095182851" > Private Post</ a ></ p >
</ header >
< p > Check out my new ride!</ p >
< iframe src = "https://video.example.com/embed?id=92469812" allowfullscreen ></ iframe >
</ article > Neither allow nor allowfullscreen can grant access to a feature in an
iframe element's content navigable if the element's node
document is not already allowed to use that feature.
To determine whether a Document object document
is allowed to use the policy-controlled-feature feature, run these
steps:
If document's browsing context is null, then return false.
If document is not fully active, then return false.
If the result of running is feature enabled in document
for origin on feature, document, and document's origin is "Enabled", then return
true.
Return false.
Because they only influence the permissions policy of the content
navigable's active document, the allow and allowfullscreen attributes only take effect when the
content navigable of the iframe is navigated. Adding or removing them has no effect on an already-loaded
document.
The iframe element supports dimension attributes for cases where the
embedded content has specific dimensions (e.g. ad units have well-defined dimensions).
An iframe element never has fallback content, as it will always
create a new child navigable, regardless of whether the specified initial
contents are successfully used.
The referrerpolicy attribute is a
referrer policy attribute. Its purpose is to set the referrer policy
used when processing the iframe
attributes. [REFERRERPOLICY]
The loading attribute is a lazy
loading attribute. Its purpose is to indicate the policy for loading iframe
elements that are outside the viewport.
When the loading attribute's state is changed to the
Eager state, the user agent must run these
steps:
Let resumptionSteps be the iframe element's lazy load
resumption steps.
If resumptionSteps is null, then return.
Set the iframe's lazy load resumption steps to null.
Invoke resumptionSteps.
Descendants of iframe elements represent nothing. (In legacy user agents that do
not support iframe elements, the contents would be parsed as markup that could act as
fallback content.)
The HTML parser treats markup inside iframe elements as
text.
Support in all current engines.
The srcdoc getter steps are:
Let attribute be the result of running get an attribute by namespace and local
name given null, srcdoc's local name, and this.
If attribute is null, then return the empty string.
Return attribute's value.
The srcdoc setter steps
are:
Let compliantString be the result of invoking the Get Trusted Type compliant string algorithm with TrustedHTML, this's relevant global
object, the given value, "HTMLIFrameElement srcdoc", and "script".
Set an attribute value given
this, srcdoc's local name, and
compliantString.
The supported tokens for sandbox's DOMTokenList are the allowed
values defined in the sandbox attribute and supported by
the user agent.
HTMLIFrameElement/referrerPolicy
Support in all current engines.
The referrerPolicy IDL attribute must
reflect the referrerpolicy content
attribute, limited to only known values.
The loading IDL attribute must reflect the loading content attribute, limited to only known
values.
HTMLIFrameElement/contentDocument
Support in all current engines.
The contentDocument getter steps are to return
this's content document.
HTMLIFrameElement/contentWindow
Support in all current engines.
The contentWindow getter steps are to return
this's content window.
Here is an example of a page using an iframe to include advertising from an
advertising broker:
< iframe src = "https://ads.example.com/?customerid=923513721&format=banner"
width = "468" height = "60" ></ iframe > embed elementSupport in all current engines.
Support in all current engines.
src — Address of the resource
type — Type of embedded resource
width — Horizontal dimension
height — Vertical dimension
[Exposed =Window ]
interface HTMLEmbedElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions , ReflectURL ] attribute USVString src ;
[CEReactions , Reflect ] attribute DOMString type ;
[CEReactions , Reflect ] attribute DOMString width ;
[CEReactions , Reflect ] attribute DOMString height ;
Document ? getSVGDocument ();
// also has obsolete members
};The embed element provides an integration point for an external application or
interactive content.
The src attribute
gives the URL of the resource being embedded. The attribute, if present, must contain
a valid non-empty URL potentially surrounded by spaces.
If the itemprop attribute is specified on an
embed element, then the src attribute must also
be specified.
The type attribute,
if present, gives the MIME type by which the plugin to instantiate is selected. The
value must be a valid MIME type string. If both the type attribute and the src
attribute are present, then the type attribute must specify
the same type as the explicit Content-Type metadata of the
resource given by the src attribute.
While any of the following conditions are occurring, any plugin instantiated for
the element must be removed, and the embed element represents
nothing:
The element has neither a src attribute nor a type attribute.
The element has a media element ancestor.
The element has an ancestor object element that is not showing its
fallback content.
An embed element is said to be potentially
active when the following conditions are all met simultaneously:
The element is in a document or was in a document the last time the event loop reached step 1.
The element's node document is fully active.
The element has either a src attribute set or a
type attribute set (or both).
The element's src attribute is either absent or its
value is not the empty string.
The element is not a descendant of a media element.
The element is not a descendant of an object element that is not showing its
fallback content.
The element is being rendered, or was being rendered the last time the event loop reached step 1.
Whenever an embed element that was not potentially active becomes potentially active, and whenever a potentially active embed element that is
remaining potentially active has its src attribute set, changed, or removed or its type attribute set, changed, or removed, the user agent must
queue an element task on the embed task source given the element
to run the embed element setup steps for that element.
The embed element setup steps for a given embed element
element are as follows:
If another task has since been queued to run the
embed element setup steps for element, then return.
If element has a src attribute set, then:
Let url be the result of encoding-parsing a URL given
element's src attribute's value, relative to
element's node document.
If url is failure, then return.
Let request be a new request whose
URL is url, client is element's node
document's relevant settings object, destination is "embed",
credentials mode is "include", mode is "navigate", initiator
type is "embed", and whose use-URL-credentials flag
is set.
Fetch request, with processResponse set to the following steps given response response:
If another task has since been queued to run
the embed element setup steps for element, then
return.
If response is a network error, then fire an event named load at element, and return.
Let type be the result of determining the type of content given element and response.
Switch on type:
Display no plugin for element.
If element's content navigable is null, then create a new child navigable for element.
Navigate element's content
navigable to response's URL using element's node
document, with response set to
response, and historyHandling set to "replace".
element's src attribute
does not get updated if the content navigable gets further navigated to
other locations.
element now represents its content navigable.
Fetching the resource must delay the load event of element's node document.
Otherwise, display no plugin for element.
To determine the type of the content given an
embed element element and a response response, run the following steps:
If element has a type attribute, and that
attribute's value is a type that a plugin supports, then return the value of the
type attribute.
If the path component of response's url matches a pattern that a plugin supports, then return the type that that plugin can handle.
For example, a plugin might say that it can handle URLs with path components that end with the four character string
".swf".
If response has explicit Content-Type metadata, and that value is a type that a plugin supports, then return that value.
Return null.
It is intentional that the above algorithm allows response to have a non-ok status. This allows servers to return data for plugins even with error responses (e.g., HTTP 500 Internal Server Error codes can still contain plugin data).
To display no plugin for an embed element element:
Destroy a child navigable given element.
Display an indication that no plugin could be found for element, as the contents of element.
element now represents nothing.
The embed element has no fallback content; its
descendants are ignored.
Whenever an embed element that was potentially
active stops being potentially active, any
plugin that had been instantiated for that element must be unloaded.
The embed element potentially delays the load event.
The embed element supports dimension attributes.
object 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.
data — Address of the resource
type — Type of embedded resource
name — Name of content navigable
form — Associates the element with a form element
width — Horizontal dimension
height — Vertical dimension
[Exposed =Window ]
interface HTMLObjectElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions , ReflectURL ] attribute USVString data ;
[CEReactions , Reflect ] attribute DOMString type ;
[CEReactions , Reflect ] attribute DOMString name ;
readonly attribute HTMLFormElement ? form ;
[CEReactions , Reflect ] attribute DOMString width ;
[CEReactions , Reflect ] attribute DOMString height ;
readonly attribute Document ? contentDocument ;
readonly attribute WindowProxy ? contentWindow ;
Document ? getSVGDocument ();
readonly attribute boolean willValidate ;
readonly attribute ValidityState validity ;
readonly attribute DOMString validationMessage ;
boolean checkValidity ();
boolean reportValidity ();
undefined setCustomValidity (DOMString error );
// also has obsolete members
};Depending on the type of content instantiated by the
object element, the node also supports other
interfaces.
The object element can represent an external resource, which, depending on the
type of the resource, will either be treated as an image or as a child
navigable.
The data attribute
specifies the URL of the resource. It must be present, and must contain a
valid non-empty URL potentially surrounded by spaces.
The type attribute,
if present, specifies the type of the resource. If present, the attribute must be a valid
MIME type string.
The name
attribute, if present, must be a valid navigable target name. The given value is
used to name the element's content navigable, if applicable, and if present when the
element's content navigable is created.
Whenever one of the following conditions occur:
object elements changes to or from showing its
fallback content,
classid attribute is set, changed, or
removed,
classid attribute is not present, and
its data attribute is set, changed, or removed,
classid attribute nor its
data attribute are present, and its type attribute is set, changed, or removed,
...the user agent must queue an element task on the DOM manipulation task
source given the object element to run the following steps to (re)determine
what the object element represents. This task
being queued or actively running must delay the load
event of the element's node document.
If the user has indicated a preference that this object element's fallback
content be shown instead of the element's usual behavior, then jump to the step below
labeled fallback.
For example, a user could ask for the element's fallback content to be shown because that content uses a format that the user finds more accessible.
If the element has an ancestor media element, or has an ancestor
object element that is not showing its fallback content, or if
the element is not in a document whose browsing
context is non-null, or if the element's node document is not fully
active, or if the element is still in the stack of open elements of an
HTML parser or XML parser, or if the element is not being
rendered, then jump to the step below labeled fallback.
If the data attribute is present and its value is
not the empty string, then:
If the type attribute is present and its value is
not a type that the user agent supports, then the user agent may jump to the step below labeled
fallback without fetching the content to examine its real type.
Let url be the result of encoding-parsing a URL given the data attribute's value, relative to the element's node
document.
If url is failure, then fire an
event named error at the element and jump to the step
below labeled fallback.
Let request be a new request whose
URL is url, client is the element's node document's
relevant settings object, destination is "object",
credentials mode is "include", mode is "navigate", initiator
type is "object", and whose use-URL-credentials
flag is set.
Fetch request.
Fetching the resource must delay the load event of the element's node document until the task that is queued by the networking task source once the resource has been fetched (defined next) has been run.
If the resource is not yet available (e.g. because the resource was not available in the cache, so that loading the resource required making a request over the network), then jump to the step below labeled fallback. The task that is queued by the networking task source once the resource is available must restart this algorithm from this step. Resources can load incrementally; user agents may opt to consider a resource "available" whenever enough data has been obtained to begin processing the resource.
If the load failed (e.g. there was an HTTP 404 error, there was a DNS error), fire an event named error
at the element, then jump to the step below labeled fallback.
Determine the resource type, as follows:
Let the resource type be unknown.
If the user agent is configured to strictly obey Content-Type headers for this resource, and the resource has associated Content-Type metadata, then let the resource type be the type specified in the resource's Content-Type metadata, and jump to the step below labeled handler.
This can introduce a vulnerability, wherein a site is trying to embed a resource that uses a particular type, but the remote site overrides that and instead furnishes the user agent with a resource that triggers a different type of content with different security characteristics.
Run the appropriate set of steps from the following list:
Let binary be false.
If the type specified in the resource's Content-Type
metadata is "text/plain", and the result of applying the rules for distinguishing if a resource is
text or binary to the resource is that the resource is not
text/plain, then set binary to true.
If the type specified in the resource's Content-Type
metadata is "application/octet-stream", then set binary to true.
If binary is false, then let the resource type be the type specified in the resource's Content-Type metadata, and jump to the step below labeled handler.
If there is a type attribute present on the
object element, and its value is not application/octet-stream,
then run the following steps:
If the attribute's value is a type that starts with "image/" that is
not also an XML MIME type, then let the resource type be the
type specified in that type attribute.
Jump to the step below labeled handler.
If there is a type attribute present on the
object element, then let the tentative type be the type
specified in that type attribute.
Otherwise, let tentative type be the computed type of the resource.
If tentative type is not
application/octet-stream, then let resource type be
tentative type and jump to the step below labeled
handler.
If applying the URL parser algorithm to the URL of the specified resource (after any redirects) results in a URL record whose path component matches a pattern that a plugin supports, then let resource type be the type that that plugin can handle.
For example, a plugin might say that it can handle resources with path components that end with the four character string
".swf".
It is possible for this step to finish, or for one of the substeps above to jump straight to the next step, with resource type still being unknown. In both cases, the next step will trigger fallback.
Handler: Handle the content as given by the first of the following cases that matches:
image/"If the object element's content navigable is null, then
create a new child navigable for the element.
Let response be the response from fetch.
If response's URL does not match about:blank, then
navigate the element's content navigable to
response's URL using the element's
node document, with historyHandling set to
"replace".
The data attribute of the
object element doesn't get updated if the content navigable gets
further navigated to other locations.
The object element represents its content
navigable.
image/", and support
for images has not been disabledDestroy a child navigable given the object element.
Apply the image sniffing rules to determine the type of the image.
The object element represents the specified image.
If the image cannot be rendered, e.g. because it is malformed or in an unsupported format, jump to the step below labeled fallback.
The given resource type is not supported. Jump to the step below labeled fallback.
If the previous step ended with the resource type being unknown, this is the case that is triggered.
The element's contents are not part of what the object element
represents.
If the object element does not represent its content navigable,
then once the resource is completely loaded, queue an element task on the
DOM manipulation task source given the object element to fire an event named load
at the element.
If the element does represent its content navigable,
then an analogous task will be queued when the created Document is completely finished loading.
Return.
Fallback: The object element represents the element's
children. This is the element's fallback content. Destroy a child
navigable given the element.
Due to the algorithm above, the contents of object elements act as fallback
content, used only when referenced resources can't be shown (e.g. because it returned a 404
error). This allows multiple object elements to be nested inside each other,
targeting multiple user agents with different capabilities, with the user agent picking the first
one it supports.
The object element potentially delays the load event.
The form attribute is used to explicitly associate the
object element with its form owner.
The object element supports dimension attributes.
HTMLObjectElement/contentDocument
Support in all current engines.
The contentDocument getter steps are to return
this's content document.
HTMLObjectElement/contentWindow
Support in all current engines.
The contentWindow getter steps are to return
this's content window.
The willValidate, validity, and validationMessage attributes, and the checkValidity(), reportValidity(), and setCustomValidity() methods, are part of the
constraint validation API. The form IDL attribute
is part of the element's forms API.
In this example, an HTML page is embedded in another using the object
element.
< figure >
< object data = "clock.html" ></ object >
< figcaption > My HTML Clock</ figcaption >
</ figure > video elementSupport in all current engines.
Support in all current engines.
controls attribute: Interactive content.src attribute:
zero or more track elements, then
transparent, but with no media element descendants.src attribute: zero or more source elements, then
zero or more track elements, then
transparent, but with no media element descendants.src — Address of the resource
crossorigin — How the element handles crossorigin requests
poster — Poster frame to show prior to video playback
preload — Hints how much buffering the media resource will likely need
autoplay — Hint that the media resource can be started automatically when the page is loaded
playsinline — Encourage the user agent to display video content within the element's playback area
loop — Whether to loop the media resource
muted — Whether to mute the media resource by default
controls — Show user agent controls
width — Horizontal dimension
height — Vertical dimension
[Exposed =Window ]
interface HTMLVideoElement : HTMLMediaElement {
[HTMLConstructor ] constructor ();
[CEReactions , Reflect ] attribute unsigned long width ;
[CEReactions , Reflect ] attribute unsigned long height ;
readonly attribute unsigned long videoWidth ;
readonly attribute unsigned long videoHeight ;
[CEReactions , ReflectURL ] attribute USVString poster ;
[CEReactions , Reflect ] attribute boolean playsInline ;
};A video element is used for playing videos or movies, and audio files with
captions.
Content may be provided inside the video element. User agents
should not show this content to the user; it is intended for older web browsers which do
not support video, so that text can be shown to the users of these older browsers
informing them of how to access the video contents.
In particular, this content is not intended to address accessibility concerns. To
make video content accessible to the partially sighted, the blind, the hard-of-hearing, the deaf,
and those with other physical or cognitive disabilities, a variety of features are available.
Captions can be provided, either embedded in the video stream or as external files using the
track element. Sign-language tracks can be embedded in the video stream. Audio
descriptions can be embedded in the video stream or in text form using a WebVTT file
referenced using the track element and synthesized into speech by the user agent.
WebVTT can also be used to provide chapter titles. For users who would rather not use a media
element at all, transcripts or other textual alternatives can be provided by simply linking to
them in the prose near the video element. [WEBVTT]
The video element is a media element whose media data is
ostensibly video data, possibly with associated audio data.
The src, crossorigin,
preload, autoplay,
loop, muted, and controls attributes are the attributes common to all media elements.
The poster
attribute gives the URL of an image file that the user agent can show while no video
data is available. The attribute, if present, must contain a valid non-empty URL
potentially surrounded by spaces.
If the specified resource is to be used, then, when the element is created or when the poster attribute is set, changed, or removed, the user agent must
run the following steps to determine the element's poster frame (regardless of the
value of the element's show poster flag):
If there is an existing instance of this algorithm running for this video
element, abort that instance of this algorithm without changing the poster
frame.
If the poster attribute's value is the empty string
or if the attribute is absent, then there is no poster frame; return.
Let url be the result of encoding-parsing a URL given the poster attribute's value, relative to the element's node
document.
If url is failure, then return. There is no poster frame.
Let request be a new request whose URL is url, client is the element's node document's
relevant settings object, destination is "image", initiator type is "video",
credentials mode is "include", and whose use-URL-credentials flag is set.
Fetch request. This must delay the load event of the element's node document.
If an image is thus obtained, the poster frame is that image. Otherwise, there is no poster frame.
The image given by the poster attribute,
the poster frame, is intended to be a representative frame of the
video (typically one of the first non-blank frames) that gives the user an idea of what the video
is like.
The playsinline attribute is a boolean
attribute. If present, it serves as a hint to the user agent that the video ought to be
displayed "inline" in the document by default, constrained to the element's playback area, instead
of being displayed fullscreen or in an independent resizable window.
The absence of the playsinline
attribute does not imply that the video will display fullscreen by default. Indeed, most user
agents have chosen to play all videos inline by default, and in such user agents the playsinline attribute has no effect.
A video element represents what is given for the first matching condition in the
list below:
readyState attribute is either HAVE_NOTHING, or HAVE_METADATA but no video data has yet been obtained at
all, or the element's readyState attribute is any
subsequent value but the media resource does not have a video channel)video element represents its poster frame, if any,
or else transparent black with no natural dimensions.video element is paused, the current playback position is the first frame of video,
and the element's show poster flag is setvideo element represents its poster frame, if any,
or else the first frame of the video.video element is paused, and the
frame of video corresponding to the current playback
position is not available (e.g. because the video is seeking or buffering)video element is neither potentially playing nor paused (e.g. when seeking or stalled)video element represents the last frame of the video to have
been rendered.video element is pausedvideo element represents the frame of video corresponding to
the current playback position.video element has a video channel and is potentially
playing)video element represents the frame of video at the continuously
increasing "current" position. When the
current playback position changes such that the last frame rendered is no longer the
frame corresponding to the current playback position in the video, the new frame
must be rendered.Frames of video must be obtained from the video track that was selected when the event loop last reached step 1.
Which frame in a video stream corresponds to a particular playback position is defined by the video stream's format.
The video element also represents any text track cues whose text track cue active flag is set and whose
text track is in the showing mode, and any
audio from the media resource, at the current playback position.
Any audio associated with the media resource must, if played, be played synchronized with the current playback position, at the element's effective media volume. The user agent must play the audio from audio tracks that were enabled when the event loop last reached step 1.
In addition to the above, the user agent may provide messages to the user (such as "buffering", "no video loaded", "error", or more detailed information) by overlaying text or icons on the video or other areas of the element's playback area, or in another appropriate manner.
User agents that cannot render the video may instead make the element represent a link to an external video playback utility or to the video data itself.
When a video element's media resource has a video channel, the
element provides a paint source whose width is the media resource's
natural width, whose height is the
media resource's natural
height, and whose appearance is the frame of video corresponding to the current playback position, if that is available, or else
(e.g. when the video is seeking or buffering) its previous appearance, if any, or else (e.g.
because the video is still loading the first frame) blackness.
video.videoWidthSupport in all current engines.
video.videoHeightSupport in all current engines.
These attributes return the natural dimensions of the video, or 0 if the dimensions are not known.
The natural width and natural height of the media resource are the dimensions of the resource in CSS pixels after taking into account the resource's dimensions, aspect ratio, clean aperture, resolution, and so forth, as defined for the format used by the resource. If an anamorphic format does not define how to apply the aspect ratio to the video data's dimensions to obtain the "correct" dimensions, then the user agent must apply the ratio by increasing one dimension and leaving the other unchanged.
The videoWidth IDL attribute must return the natural width of the video in CSS pixels. The videoHeight IDL attribute must return the natural height of the video in CSS pixels. If the element's readyState attribute is HAVE_NOTHING, then the attributes must return 0.
Whenever the natural width
or natural height of the video changes
(including, for example, because the selected video
track was changed), if the element's readyState
attribute is not HAVE_NOTHING, the user agent must
queue a media element task given the media element to fire an event named resize at the media element.
The video element supports dimension attributes.
In the absence of style rules to the contrary, video content should be rendered inside the element's playback area such that the video content is shown centered in the playback area at the largest possible size that fits completely within it, with the video content's aspect ratio being preserved. Thus, if the aspect ratio of the playback area does not match the aspect ratio of the video, the video will be shown letterboxed or pillarboxed. Areas of the element's playback area that do not contain the video represent nothing.
In user agents that implement CSS, the above requirement can be implemented by using the style rule suggested in the Rendering section.
The natural width of a video element's playback area is the
natural width of the poster frame, if that is available and the
element currently represents its poster frame; otherwise, it is the natural width of the video resource, if that is
available; otherwise the natural width is missing.
The natural height of a video element's playback area is the
natural height of the poster frame, if that is available and the
element currently represents its poster frame; otherwise it is the natural height of the video resource, if that is
available; otherwise the natural height is missing.
The default object size is a width of 300 CSS pixels and a height of 150 CSS pixels. [CSSIMAGES]
User agents should provide controls to enable or disable the display of closed captions, audio description tracks, and other additional data associated with the video stream, though such features should, again, not interfere with the page's normal rendering.
User agents may allow users to view the video content in manners more suitable to the user,
such as fullscreen or in an independent resizable window. User agents may even trigger such a
viewing mode by default upon playing a video, although they should not do so when the playsinline attribute is specified. As with the other user
interface features, controls to enable this should not interfere with the page's normal rendering
unless the user agent is exposing a user
interface. In such an independent viewing mode, however, user agents may make full user
interfaces visible, even if the controls attribute is
absent.
User agents may allow video playback to affect system features that could interfere with the user's experience; for example, user agents could disable screensavers while video playback is in progress.
This example shows how to detect when a video has failed to play correctly:
< script >
function failed( e) {
// video playback failed - show a message saying why
switch ( e. target. error. code) {
case e. target. error. MEDIA_ERR_ABORTED:
alert( 'You aborted the video playback.' );
break ;
case e. target. error. MEDIA_ERR_NETWORK:
alert( 'A network error caused the video download to fail part-way.' );
break ;
case e. target. error. MEDIA_ERR_DECODE:
alert( 'The video playback was aborted due to a corruption problem or because the video used features your browser did not support.' );
break ;
case e. target. error. MEDIA_ERR_SRC_NOT_SUPPORTED:
alert( 'The video could not be loaded, either because the server or network failed or because the format is not supported.' );
break ;
default :
alert( 'An unknown error occurred.' );
break ;
}
}
</ script >
< p >< video src = "tgif.vid" autoplay controls onerror = "failed(event)" ></ video ></ p >
< p >< a href = "tgif.vid" > Download the video file</ a > .</ p > audio elementSupport in all current engines.
Support in all current engines.
controls attribute: Interactive content.controls attribute: Palpable content.src attribute:
zero or more track elements, then
transparent, but with no media element descendants.src attribute: zero or more source elements, then
zero or more track elements, then
transparent, but with no media element descendants.src — Address of the resource
crossorigin — How the element handles crossorigin requests
preload — Hints how much buffering the media resource will likely need
autoplay — Hint that the media resource can be started automatically when the page is loaded
loop — Whether to loop the media resource
muted — Whether to mute the media resource by default
controls — Show user agent controls
[Exposed =Window ,
LegacyFactoryFunction =Audio (optional DOMString src )]
interface HTMLAudioElement : HTMLMediaElement {
[HTMLConstructor ] constructor ();
};An audio element represents a sound or audio stream.
Content may be provided inside the audio element. User agents
should not show this content to the user; it is intended for older web browsers which do
not support audio, so that text can be shown to the users of these older browsers
informing them of how to access the audio contents.
In particular, this content is not intended to address accessibility concerns. To
make audio content accessible to the deaf or to those with other physical or cognitive
disabilities, a variety of features are available. If captions or a sign language video are
available, the video element can be used instead of the audio element to
play the audio, allowing users to enable the visual alternatives. Chapter titles can be provided
to aid navigation, using the track element and a WebVTT file. And,
naturally, transcripts or other textual alternatives can be provided by simply linking to them in
the prose near the audio element. [WEBVTT]
The audio element is a media element whose media data is
ostensibly audio data.
The src, crossorigin,
preload, autoplay,
loop, muted, and controls attributes are the attributes common to all media elements.
audio = new Audio([ url ])Support in all current engines.
Returns a new audio element, with the src
attribute set to the value passed in the argument, if applicable.
A legacy factory function is provided for creating HTMLAudioElement objects (in
addition to the factory methods from DOM such as createElement()): Audio(src). When invoked, the legacy factory function
must perform the following steps:
Let document be the current global object's associated Document.
Let audio be the result of creating an
element given document, "audio", and the HTML
namespace.
Set an attribute value for
audio using "preload" and "auto".
If src is given, then set
an attribute value for audio using "src"
and src. (This will cause the user
agent to invoke the object's resource selection
algorithm before returning.)
Return audio.
track elementSupport in all current engines.
Support in all current engines.
Support in all current engines.
kind — The type of text track
src — Address of the resource
srclang — Language of the text track
label — User-visible label
default — Enable the track if no other text track is more suitable
[Exposed =Window ]
interface HTMLTrackElement : HTMLElement {
[HTMLConstructor ] constructor ();
[CEReactions ] attribute DOMString kind ;
[CEReactions , ReflectURL ] attribute USVString src ;
[CEReactions , Reflect ] attribute DOMString srclang ;
[CEReactions , Reflect ] attribute DOMString label ;
[CEReactions , Reflect ] attribute boolean default ;
const unsigned short NONE = 0;
const unsigned short LOADING = 1;
const unsigned short LOADED = 2;
const unsigned short ERROR = 3;
readonly attribute unsigned short readyState ;
readonly attribute TextTrack track ;
};The track element allows authors to specify explicit external timed text tracks for media elements. It
does not represent anything on its own.
The kind attribute is
an enumerated attribute with the following keywords and states:
| Keyword | State | Brief description |
|---|---|---|
subtitles
| Subtitles | Transcription or translation of the dialogue, suitable for when the sound is available but not understood (e.g. because the user does not understand the language of the media resource's audio track). Overlaid on the video. |
captions
| Captions | Transcription or translation of the dialogue, sound effects, relevant musical cues, and other relevant audio information, suitable for when sound is unavailable or not clearly audible (e.g. because it is muted, drowned-out by ambient noise, or because the user is deaf). Overlaid on the video; labeled as appropriate for the hard-of-hearing. |
descriptions
| Descriptions | Textual descriptions of the video component of the media resource, intended for audio synthesis when the visual component is obscured, unavailable, or not usable (e.g. because the user is interacting with the application without a screen while driving, or because the user is blind). Synthesized as audio. |
chapters
| Chapters metadata | Tracks intended for use from script. Not displayed by the user agent. |
metadata
| Metadata |
The attribute's missing value default is the subtitles state, and its invalid value default is the metadata state.
The src attribute
gives the URL of the text track data. The value must be a valid non-empty URL
potentially surrounded by spaces. This attribute must be present.
The element has an associated track URL (a string), initially the empty string.
When the element's src attribute is set, run these steps:
Let trackURL be failure.
Let value be the element's src attribute
value.
If value is not the empty string, then set trackURL to the result of encoding-parsing-and-serializing a URL given value, relative to the element's node document.
Set the element's track URL to trackURL if it is not failure; otherwise to the empty string.
If the element's track URL identifies a WebVTT resource, and the element's kind attribute is not in the chapters metadata or metadata state, then the WebVTT file must be a
WebVTT file using cue text. [WEBVTT]
The srclang
attribute gives the language of the text track data. The value must be a valid BCP 47 language
tag. This attribute must be present if the element's kind
attribute is in the subtitles state.
[BCP47]
If the element has a srclang attribute whose value is
not the empty string, then the element's track language is the value of the attribute.
Otherwise, the element has no track language.
The label attribute
gives a user-readable title for the track. This title is used by user agents when listing subtitle, caption, and audio description tracks in their user interface.
The value of the label attribute, if the attribute is
present, must not be the empty string. Furthermore, there must not be two track
element children of the same media element whose kind attributes are in the same state, whose srclang attributes are both missing or have values that
represent the same language, and whose label attributes are
again both missing or both have the same value.
If the element has a label attribute whose value is not
the empty string, then the element's track label is the value of the attribute.
Otherwise, the element's track label is an empty string.
The default
attribute is a boolean attribute, which, if specified, indicates that the track is to
be enabled if the user's preferences do not indicate that another track would be more
appropriate.
Each media element must have no more than one track element child
whose kind attribute is in the subtitles or captions state and whose default attribute is specified.
Each media element must have no more than one track element child
whose kind attribute is in the description state and whose default attribute is specified.
Each media element must have no more than one track element child
whose kind attribute is in the chapters metadata state and whose default attribute is specified.
There is no limit on the number of track elements whose kind attribute is in the metadata state and whose default attribute is specified.
track.readyStateReturns the text track readiness state, represented by a number from the following list:
track.NONE (0)The text track not loaded state.
track.LOADING (1)The text track loading state.
track.LOADED (2)The text track loaded state.
track.ERROR (3)The text track failed to load state.
track.trackReturns the TextTrack object corresponding to the text track of the
track element.
The readyState attribute must return the numeric value
corresponding to the text track readiness state of the track element's
text track, as defined by the following list:
NONE (numeric value 0)LOADING (numeric value 1)LOADED (numeric value 2)ERROR (numeric value 3)The track IDL
attribute must, on getting, return the track element's text track's
corresponding TextTrack object.
The kind IDL
attribute must reflect the content attribute of the same name, limited to only
known values.
This video has subtitles in several languages:
< video src = "brave.webm" >
< track kind = subtitles src = brave.en.vtt srclang = en label = "English" >
< track kind = captions src = brave.en.hoh.vtt srclang = en label = "English for the Hard of Hearing" >
< track kind = subtitles src = brave.fr.vtt srclang = fr lang = fr label = "Français" >
< track kind = subtitles src = brave.de.vtt srclang = de lang = de label = "Deutsch" >
</ video > (The lang attributes on the last two describe the language of
the label attribute, not the language of the subtitles
themselves. The language of the subtitles is given by the srclang attribute.)
HTMLMediaElement objects (audio and video, in this
specification) are simply known as media elements.
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.
enum CanPlayTypeResult { "" /* empty string */, " maybe " , " probably " };
typedef (MediaStream or MediaSource or Blob ) MediaProvider ;
[Exposed =Window ]
interface HTMLMediaElement : HTMLElement {
// error state
readonly attribute MediaError ? error ;
// network state
[CEReactions , ReflectURL ] attribute USVString src ;
attribute MediaProvider ? srcObject ;
readonly attribute USVString currentSrc ;
[CEReactions ] attribute DOMString ? crossOrigin ;
const unsigned short NETWORK_EMPTY = 0;
const unsigned short NETWORK_IDLE = 1;
const unsigned short NETWORK_LOADING = 2;
const unsigned short NETWORK_NO_SOURCE = 3;
readonly attribute unsigned short networkState ;
[CEReactions ] attribute DOMString preload ;
readonly attribute TimeRanges buffered ;
undefined load ();
CanPlayTypeResult canPlayType (DOMString type );
// ready state
const unsigned short HAVE_NOTHING = 0;
const unsigned short HAVE_METADATA = 1;
const unsigned short HAVE_CURRENT_DATA = 2;
const unsigned short HAVE_FUTURE_DATA = 3;
const unsigned short HAVE_ENOUGH_DATA = 4;
readonly attribute unsigned short readyState ;
readonly attribute boolean seeking ;
// playback state
attribute double currentTime ;
undefined fastSeek (double time );
readonly attribute unrestricted double duration ;
object getStartDate ();
readonly attribute boolean paused ;
attribute double defaultPlaybackRate ;
attribute double playbackRate ;
attribute boolean preservesPitch ;
readonly attribute TimeRanges played ;
readonly attribute TimeRanges seekable ;
readonly attribute boolean ended ;
[CEReactions , Reflect ] attribute boolean autoplay ;
[CEReactions , Reflect ] attribute boolean loop ;
Promise <undefined > play ();
undefined pause ();
// controls
[CEReactions , Reflect ] attribute boolean controls ;
attribute double volume ;
attribute boolean muted ;
[CEReactions , Reflect="muted"] attribute boolean defaultMuted ;
// tracks
[SameObject ] readonly attribute AudioTrackList audioTracks ;
[SameObject ] readonly attribute VideoTrackList videoTracks ;
[SameObject ] readonly attribute TextTrackList textTracks ;
TextTrack addTextTrack (TextTrackKind kind , optional DOMString label = "", optional DOMString language = "");
};The media element attributes, src, crossorigin, preload, autoplay,
loop, muted, and
controls, apply to all media elements. They are defined in this section.
Media elements are used to present audio data, or video and audio data, to the user. This is referred to as media data in this section, since this section applies equally to media elements for audio or for video. The term media resource is used to refer to the complete set of media data, e.g. the complete video file, or complete audio file.
A media resource has an associated
origin, which is either "none",
"multiple", "rewritten", or an
origin. It is initially set to "none".
A media resource can have multiple audio and video tracks. For the purposes of a
media element, the video data of the media resource is only that of the
currently selected track (if any) as given by the element's videoTracks attribute when the event loop last
reached step 1, and the audio data of the media resource is the result of mixing all
the currently enabled tracks (if any) given by the element's audioTracks attribute when the event loop last
reached step 1.
Both audio and video elements can be used for both audio
and video. The main difference between the two is simply that the audio element has
no playback area for visual content (such as video or captions), whereas the video
element does.
Each media element has a unique media element event task source.
To queue a media element task with a media element element and a series of steps steps, queue an element task on the media element's media element event task source given element and steps.
Support in all current engines.
media.errorSupport in all current engines.
Returns a MediaError object representing the current error state of the
element.
Returns null if there is no error.
All media elements have an associated error status, which
records the last error the element encountered since its resource selection algorithm was last invoked. The
error attribute,
on getting, must return the MediaError object created for this last error, or null if
there has not been an error.
[Exposed =Window ]
interface MediaError {
const unsigned short MEDIA_ERR_ABORTED = 1;
const unsigned short MEDIA_ERR_NETWORK = 2;
const unsigned short MEDIA_ERR_DECODE = 3;
const unsigned short MEDIA_ERR_SRC_NOT_SUPPORTED = 4;
readonly attribute unsigned short code ;
readonly attribute DOMString message ;
};media.error.codeSupport in all current engines.
Returns the current error's error code, from the list below.
media.error.messageSupport in all current engines.
Returns a specific informative diagnostic message about the error condition encountered. The message and message format are not generally uniform across different user agents. If no such message is available, then the empty string is returned.
Every MediaError object has a message, which is a string, and a code, which is one of the following:
MEDIA_ERR_ABORTED (numeric value 1)MEDIA_ERR_NETWORK (numeric value 2)MEDIA_ERR_DECODE (numeric value 3)MEDIA_ERR_SRC_NOT_SUPPORTED (numeric value 4)src
attribute or assigned media provider object was not suitable.To create a MediaError, given an
error code which is one of the above values, return a new MediaError object whose
code is the given error code and whose message is a string containing any details the user
agent is able to supply about the cause of the error condition, or the empty string if the user
agent is unable to supply such details. This message string must not contain only the information
already available via the supplied error code; for example, it must not simply be a translation of
the code into a string format. If no additional information is available beyond that provided by
the error code, the message must be set to the
empty string.
The code
getter steps are to return this's code.
The message
getter steps are to return this's message.
The src content
attribute on media elements gives the URL of the
media resource (video, audio) to show. The attribute, if present, must contain a valid
non-empty URL potentially surrounded by spaces.
If the itemprop attribute is specified on the media
element, then the src attribute must also be
specified.
The crossorigin content attribute on media elements is a CORS settings attribute.
If a media element is created with a
src attribute, the user agent must immediately invoke the
media element's resource selection
algorithm.
If a src attribute of a media element is set
or changed, the user agent must invoke the media element's media element load
algorithm. (Removing the src attribute does
not do this, even if there are source elements present.)
Support in all current engines.
The crossOrigin IDL attribute must reflect
the crossorigin content attribute, limited to
only known values.
A media provider object is an object that can represent a media
resource, separate from a URL. MediaStream objects,
MediaSource objects, and Blob objects are all media provider objects.
Each media element can have an assigned media provider object, which is a media provider object. When a media element is created, it has no assigned media provider object.
media.srcObject [ = source ]Support in one engine only.
Allows the media element to be assigned a media provider object.
media.currentSrcSupport in all current engines.
Returns the URL of the current media resource, if any.
Returns the empty string when there is no media resource, or it doesn't have a URL.
The currentSrc IDL attribute must initially be set to the
empty string. Its value is changed by the resource
selection algorithm defined below.
The srcObject IDL attribute, on getting, must return the
element's assigned media provider object, if any, or null otherwise. On setting, it
must set the element's assigned media provider object to the new value, and then
invoke the element's media element load algorithm.
There are three ways to specify a media resource: the srcObject IDL attribute, the src content attribute, and source elements. The IDL
attribute takes priority, followed by the content attribute, followed by the elements.
A media resource can be described in terms of its type, specifically a
MIME type, in some cases with a codecs parameter. (Whether the
codecs parameter is allowed or not depends on the MIME type.)
[RFC6381]
Types are usually somewhat incomplete descriptions; for example "video/mpeg" doesn't say anything except what the container type is, and even a
type like "video/mp4; codecs="avc1.42E01E, mp4a.40.2"" doesn't
include information like the actual bitrate (only the maximum bitrate). Thus, given a type, a user
agent can often only know whether it might be able to play media of that type (with
varying levels of confidence), or whether it definitely cannot play media of that
type.
A type that the user agent knows it cannot render is one that describes a resource that the user agent definitely does not support, for example because it doesn't recognize the container type, or it doesn't support the listed codecs.
The MIME type "application/octet-stream" with no parameters is never
a type that the user agent knows it cannot render. User agents must treat that type
as equivalent to the lack of any explicit Content-Type metadata
when it is used to label a potential media resource.
Only the MIME type "application/octet-stream" with no
parameters is special-cased here; if any parameter appears with it, it will be treated just like
any other MIME type. This is a deviation from the rule that unknown MIME type parameters should be
ignored.
media.canPlayType(type)Support in all current engines.
Returns the empty string (a negative response), "maybe", or "probably" based on how confident the user agent is that it can play media resources of the given type.
The canPlayType(type) method must return
the empty string if type is a type
that the user agent knows it cannot render or is the type
"application/octet-stream"; it must return "probably" if
the user agent is confident that the type represents a media resource that it can
render if used in with this audio or video element; and it must return
"maybe" otherwise. Implementers are encouraged to
return "maybe" unless the type can be
confidently established as being supported or not. Generally, a user agent should never return
"probably" for a type that allows the codecs parameter if that parameter is not present.
This script tests to see if the user agent supports a (fictional) new format to dynamically
decide whether to use a video element:
< section id = "video" >
< p >< a href = "playing-cats.nfv" > Download video</ a ></ p >
</ section >
< script >
const videoSection = document. getElementById( 'video' );
const videoElement = document. createElement( 'video' );
const support = videoElement. canPlayType( 'video/x-new-fictional-format;codecs="kittens,bunnies"' );
if ( support === "probably" ) {
videoElement. setAttribute( "src" , "playing-cats.nfv" );
videoSection. replaceChildren( videoElement);
}
</ script > The type attribute of the
source element allows the user agent to avoid downloading resources that use formats
it cannot render.
media.networkStateSupport in all current engines.
Returns the current state of network activity for the element, from the codes in the list below.
As media elements interact with the network, their current
network activity is represented by the networkState attribute. On getting, it must return
the current network state of the element, which must be one of the following values:
NETWORK_EMPTY (numeric value 0)NETWORK_IDLE (numeric value 1)NETWORK_LOADING (numeric value 2)NETWORK_NO_SOURCE (numeric value 3)The resource selection algorithm defined
below describes exactly when the networkState
attribute changes value and what events fire to indicate changes in this state.
media.load()Support in all current engines.
Causes the element to reset and start selecting and loading a new media resource from scratch.
All media elements have a can autoplay flag, which must begin in the true state, and a delaying-the-load-event flag, which must begin in the false state. While the delaying-the-load-event flag is true, the element must delay the load event of its document.
When the load()
method on a media element is invoked, the user agent must run the media element
load algorithm.
A media element has an associated boolean is currently stalled, which is initially false.
The media element load algorithm consists of the following steps.
Set this element's is currently stalled to false.
Abort any already-running instance of the resource selection algorithm for this element.
Let pending tasks be a list of all tasks from the media element's media element event task source in one of the task queues.
For each task in pending tasks that would resolve pending play promises or reject pending play promises, immediately resolve or reject those promises in the order the corresponding tasks were queued.
Remove each task in pending tasks from its task queue.
Basically, pending events and callbacks are discarded and promises in-flight to be resolved/rejected are resolved/rejected immediately when the media element starts loading a new resource.
If the media element's networkState is set to NETWORK_LOADING or NETWORK_IDLE, queue a media element task
given the media element to fire an event
named abort at the media element.
If the media element's networkState
is not set to NETWORK_EMPTY, then:
Queue a media element task given the media element to fire an event named emptied at the media element.
If a fetching process is in progress for the media element, the user agent should stop it.
If the media element's assigned media provider object is a
MediaSource object, then detach it.
If readyState is not set to HAVE_NOTHING, then set it to that state.
If the paused attribute is false, then:
Set the paused attribute to true.
Take pending play promises and reject pending play promises
with the result and an "AbortError"
DOMException.
If seeking is true, set it to false.
Set the current playback position to 0.
Set the official playback position to 0.
If this changed the official playback position, then queue a media
element task given the media element to fire an event named timeupdate at the media element.
Set the timeline offset to Not-a-Number (NaN).
Update the duration attribute to Not-a-Number
(NaN).
The user agent will not fire a durationchange event for this particular change of
the duration.
Set the playbackRate attribute to the value of
the defaultPlaybackRate attribute.
Set the error attribute to null and the
can autoplay flag to true.
Invoke the media element's resource selection algorithm.
Playback of any previously playing media resource for this element stops.
The resource selection algorithm for a media element is as follows. This algorithm is always invoked as part of a task, but one of the first steps in the algorithm is to return and continue running the remaining steps in parallel. In addition, this algorithm interacts closely with the event loop mechanism; in particular, it has synchronous sections (which are triggered as part of the event loop algorithm). Steps in such sections are marked with ⌛.
Set the element's networkState attribute to
the NETWORK_NO_SOURCE value.
Set the element's show poster flag to true.
Set the media element's delaying-the-load-event flag to true (this delays the load event).
Await a stable state, allowing the task that invoked this algorithm to continue. The synchronous section consists of all the remaining steps of this algorithm until the algorithm says the synchronous section has ended. (Steps in synchronous sections are marked with ⌛.)
⌛ If the media element's blocked-on-parser flag is false, then populate the list of pending text tracks.
⌛ If the media element has an assigned media provider object, then let mode be object.
⌛ Otherwise, if the media element has no assigned media provider
object but has a src
attribute, then let mode be attribute.
⌛ Otherwise, if the media element does not have an assigned media provider
object and does not have a src attribute, but does have a source element child, then
let mode be children and let candidate
be the first such source element child in tree order.
⌛ Otherwise, the media element has no assigned media provider
object and has neither a src attribute nor a source element child:
⌛ Set the networkState to NETWORK_EMPTY.
⌛ Set the element's delaying-the-load-event flag to false. This stops delaying the load event.
End the synchronous section and return.
⌛ Set the media element's networkState to NETWORK_LOADING.
⌛ Queue a media element task given the media element to
fire an event named loadstart at the media element.
Run the appropriate steps from the following list:
⌛ Set the currentSrc attribute to
the empty string.
End the synchronous section, continuing the remaining steps in parallel.
Run the resource fetch algorithm with the assigned media provider object. If that algorithm returns without aborting this one, then the load failed.
Failed with media provider: Reaching this step indicates that the media resource failed to load. Take pending play promises and queue a media element task given the media element to run the dedicated media source failure steps with the result.
Wait for the