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