Status: Last call for comments
Status: Last call for comments
Every XML and HTML document in an HTML UA is represented by a
Document object. [DOMCORE]
The document's address is an absolute URL
that is set when the Document is created. The
document's current address is an absolute URL
that can change during the lifetime of the Document,
for example when the user navigates to
a fragment identifier on the
page or when the pushState() method is called
with a new URL. The document's
current address must be set to the document's
address when the Document is created.
Interactive user agents typically expose the document's current address in their user interface.
When a Document is created by a script using the createDocument()
or createHTMLDocument()
APIs, the document's address is the same as the
document's address of the script's document.
Document objects are assumed to be XML
documents unless they are flagged as being HTML
documents when they are created. Whether a document is an
HTML document or an XML document affects the behavior of
certain APIs and the case-sensitivity of some selectors.
Status: Last call for comments
All Document objects (in user agents implementing
this specification) must also implement
the HTMLDocument interface, available using
binding-specific methods. (This is the case whether or not the
document in question is an HTML
document or indeed whether it contains any HTML
elements at all.) Document objects must also implement the document-level interface
of any other namespaces that the UA supports.
For example, if an HTML implementation also
supports SVG, then the Document object implements both
HTMLDocument and SVGDocument.
Because the HTMLDocument interface is
now obtained using binding-specific casting methods instead of
simply being the primary interface of the document object, it is no
longer defined as inheriting from Document.
[OverrideBuiltins]
interface HTMLDocument {
// resource metadata management
[PutForwards=href] readonly attribute Location location;
readonly attribute DOMString URL;
attribute DOMString domain;
readonly attribute DOMString referrer;
attribute DOMString cookie;
readonly attribute DOMString lastModified;
readonly attribute DOMString compatMode;
attribute DOMString charset;
readonly attribute DOMString characterSet;
readonly attribute DOMString defaultCharset;
readonly attribute DOMString readyState;
// DOM tree accessors
getter any (in DOMString name);
attribute DOMString title;
attribute DOMString dir;
attribute HTMLElement body;
readonly attribute HTMLHeadElement head;
readonly attribute HTMLCollection images;
readonly attribute HTMLCollection embeds;
readonly attribute HTMLCollection plugins;
readonly attribute HTMLCollection links;
readonly attribute HTMLCollection forms;
readonly attribute HTMLCollection scripts;
NodeList getElementsByName(in DOMString elementName);
NodeList getElementsByClassName(in DOMString classNames);
// dynamic markup insertion
attribute DOMString innerHTML;
HTMLDocument open(in optional DOMString type, in optional DOMString replace);
WindowProxy open(in DOMString url, in DOMString name, in DOMString features, in optional boolean replace);
void close();
void write(in DOMString... text);
void writeln(in DOMString... text);
// user interaction
Selection getSelection();
readonly attribute Element activeElement;
boolean hasFocus();
attribute DOMString designMode;
boolean execCommand(in DOMString commandId);
boolean execCommand(in DOMString commandId, in boolean showUI);
boolean execCommand(in DOMString commandId, in boolean showUI, in DOMString value);
boolean queryCommandEnabled(in DOMString commandId);
boolean queryCommandIndeterm(in DOMString commandId);
boolean queryCommandState(in DOMString commandId);
boolean queryCommandSupported(in DOMString commandId);
DOMString queryCommandValue(in DOMString commandId);
readonly attribute HTMLCollection commands;
// event handler IDL attributes
attribute Function onabort;
attribute Function onblur;
attribute Function oncanplay;
attribute Function oncanplaythrough;
attribute Function onchange;
attribute Function onclick;
attribute Function oncontextmenu;
attribute Function ondblclick;
attribute Function ondrag;
attribute Function ondragend;
attribute Function ondragenter;
attribute Function ondragleave;
attribute Function ondragover;
attribute Function ondragstart;
attribute Function ondrop;
attribute Function ondurationchange;
attribute Function onemptied;
attribute Function onended;
attribute Function onerror;
attribute Function onfocus;
attribute Function onformchange;
attribute Function onforminput;
attribute Function oninput;
attribute Function oninvalid;
attribute Function onkeydown;
attribute Function onkeypress;
attribute Function onkeyup;
attribute Function onload;
attribute Function onloadeddata;
attribute Function onloadedmetadata;
attribute Function onloadstart;
attribute Function onmousedown;
attribute Function onmousemove;
attribute Function onmouseout;
attribute Function onmouseover;
attribute Function onmouseup;
attribute Function onmousewheel;
attribute Function onpause;
attribute Function onplay;
attribute Function onplaying;
attribute Function onprogress;
attribute Function onratechange;
attribute Function onreadystatechange;
attribute Function onscroll;
attribute Function onseeked;
attribute Function onseeking;
attribute Function onselect;
attribute Function onshow;
attribute Function onstalled;
attribute Function onsubmit;
attribute Function onsuspend;
attribute Function ontimeupdate;
attribute Function onvolumechange;
attribute Function onwaiting;
};
Document implements HTMLDocument;Since the HTMLDocument interface holds methods and
attributes related to a number of disparate features, the members of
this interface are described in various different sections.
Status: Last call for comments
User agents must raise a
SECURITY_ERR exception whenever any of the members of
an HTMLDocument object are accessed by scripts whose
effective script origin is not the same as the Document's effective
script origin.
Status: Last call for comments
URLReturns the document's address.
referrerReturns the
address 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 URL
attribute must return the document's address.
The referrer attribute
must return either the current address of the active document
of the source browsing context at the time the
navigation was started (that is, the page which navigated the browsing context
to the current document), with any <fragment> component removed; or
the empty string if there is no such originating page, or if the UA
has been configured not to report referrers in this case, or if the
navigation was initiated for a hyperlink with a noreferrer keyword.
In the case of HTTP, the referrer IDL attribute will
match the Referer (sic) header
that was sent when fetching the current
page.
Typically user agents are configured to not report
referrers in the case where the referrer uses an encrypted protocol
and the current page does not (e.g. when navigating from an https: page to an http:
page).
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 a unique origin (in an
iframe with the sandbox attribute) or the
resource was labeled as text/html-sandboxed, a
SECURITY_ERR exception will be thrown on getting and
setting.
The cookie
attribute represents the cookies of the resource from which the
Document was created.
Some Document objects are cookie-free Document
objects. Any Document object created by the createDocument() or createHTMLDocument()
factory methods is a cookie-free Document
object. Any Document whose address does not use a server-based
naming authority is a cookie-free Document
object. Other specifications can also define
Document objects as being cookie-free Document
objects.
On getting, if the document is a
cookie-free Document object, then the user
agent must return the empty string. Otherwise, if the
Document's origin is not a
scheme/host/port tuple, the user agent must raise a
SECURITY_ERR exception. Otherwise, the user agent must
first obtain the storage mutex and then return the
cookie-string for the document's address for a
"non-HTTP" API. [COOKIES]
On setting, if the document is a cookie-free
Document object, then the user agent must do
nothing. Otherwise, if the Document's
origin is not a scheme/host/port tuple, the user agent
must raise a SECURITY_ERR exception. Otherwise, the
user agent must obtain the storage mutex and then act
as it would when receiving a set-cookie-string for
the document's address via a "non-HTTP" API, consisting
of the new value. [COOKIES]
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.
lastModifiedReturns 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:
All the numeric components above, other than the year, must be given as two digits in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9) representing the number in base ten, zero-padded if necessary. The year must be given as the shortest possible string of four or more digits in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9) 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.
compatModeIn a conforming document, returns the string "CSS1Compat". (In quirks mode
documents, returns the string "BackCompat",
but a conforming document can never trigger quirks
mode.)
A Document is always set to one of three modes:
no quirks mode, the default; quirks mode, used
typically for legacy documents; and limited quirks mode,
also known as "almost standards" mode. The mode is only ever changed
from the default by the HTML parser, based on the
presence, absence, or value of the DOCTYPE string.
The compatMode IDL
attribute must return the literal string "CSS1Compat" unless the document has been set to
quirks mode by the HTML parser, in which
case it must instead return the literal string "BackCompat".
charset [ = value ]Returns the document's character encoding.
Can be set, to dynamically change the document's character encoding.
New values that are not IANA-registered aliases supported by the user agent are ignored.
characterSetReturns the document's character encoding.
defaultCharsetReturns what might be the user agent's default character encoding. (The user agent might return another character encoding altogether, e.g. to protect the user's privacy, or if the user agent doesn't use a single default encoding.)
Documents have an associated character encoding. When a Document
object is created, the document's character encoding
must be initialized to UTF-16. Various algorithms during page
loading affect this value, as does the charset setter. [IANACHARSET]
The charset
IDL attribute must, on getting, return the preferred MIME
name of the document's character encoding. On
setting, if the new value is an IANA-registered alias for a
character encoding supported by the user agent, the document's
character encoding must be set to that character
encoding. (Otherwise, nothing happens.)
The characterSet
IDL attribute must, on getting, return the preferred MIME
name of the document's character encoding.
The defaultCharset
IDL attribute must, on getting, return the preferred MIME
name of a character encoding, possibly the user's default
encoding, or an encoding associated with the user's current
geographical location, or any arbitrary encoding name.
readyStateReturns "loading" while the Document is loading, and "complete" once it has loaded.
The readystatechange event fires on the Document object when this value changes.
Each document has a current document readiness. When a
Document object is created, it must have its
current document readiness set to the string "loading"
if the document is associated with an HTML parser or an
XML parser, or to the string "complete"
otherwise. Various algorithms during page loading affect this
value. When the value is set, the user agent must fire a
simple event named readystatechange at the
Document object.
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.
The readyState IDL
attribute must, on getting, return the current document
readiness.
Status: Last call for comments
The html element of a document is the
document's root element, if there is one and it's an
html element, or null otherwise.
headReturns 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).
title [ = value ]Returns the document's title, as given by the
title element.
Can be set, to update the document's title. If there is no
head element,
the new value is ignored.
In SVG documents, the SVGDocument interface's
title attribute takes
precedence.
The title element of a document is the
first title element in the document (in tree order), if
there is one, or null otherwise.
The title attribute must,
on getting, run the following algorithm:
If the root element is an svg
element in the "http://www.w3.org/2000/svg"
namespace, and the user agent supports SVG, then return the value
that would have been returned by the IDL attribute of the same name
on the SVGDocument interface. [SVG]
Otherwise, let value be a concatenation
of the data of all the child text
nodes of the title element, in
tree order, or the empty string if the
title element is null.
Replace any sequence of one or more consecutive space characters in value with a single U+0020 SPACE character.
Remove any leading or trailing space characters in value.
Return value.
On setting, the following algorithm must be run. Mutation events must be fired as appropriate.
If the root element is an svg
element in the "http://www.w3.org/2000/svg"
namespace, and the user agent supports SVG, then the setter must
defer to the setter for the IDL attribute of the same name on the
SVGDocument interface (if it is readonly, then this
will raise an exception). Stop the algorithm here. [SVG]
title element is null and
the head element is null, then the
attribute must do nothing. Stop the algorithm here.title element is null, then a
new title element must be created and appended to
the head element. Let element be that element. Otherwise, let element be the title
element.Text node whose data is the new value
being assigned must be appended to element.The title attribute on
the HTMLDocument interface should shadow the attribute
of the same name on the SVGDocument interface when the
user agent supports both HTML and SVG. [SVG]
body [ = value ]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 HIERARCHY_REQUEST_ERR exception.
The body element of a document is the first child of
the html element that is either a
body element or a frameset element. If
there is no such element, it is null. If the body
element is null, then when the specification requires that events be
fired at "the body element", they must instead be fired at the
Document object.
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 raise a
HIERARCHY_REQUEST_ERR exception and abort these
steps.replaceChild() method had been
called with the new value and the
incumbent body element as its two arguments respectively,
then abort these steps.imagesReturns an HTMLCollection of the img elements in the Document.
embedspluginsReturn an HTMLCollection of the embed elements in the Document.
linksReturns an HTMLCollection of the a and area elements in the Document that have href attributes.
formsReturn an HTMLCollection of the form elements in the Document.
scriptsReturn 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.
getElementsByName(name)Returns a NodeList of elements in the
Document that have a name
attribute with the value name.
getElementsByClassName(classes)getElementsByClassName(classes)Returns a NodeList of the elements in the object
on which the method was invoked (a Document or an
Element) that have all the classes given by classes.
The classes argument is interpreted as a space-separated list of classes.
The getElementsByName(name) method takes a string name, and must return a live NodeList
containing all the HTML elements in that document that
have a name attribute whose value is equal to
the name argument (in a
case-sensitive manner), in tree order. A
new NodeList object must be returned each time unless
the argument is the same as the last time the method was invoked on
this Document object, in which case the object must be
the same as the object returned by the previous call.
The getElementsByClassName(classNames) method takes a string that
contains a set of space-separated tokens representing
classes. When called, the method must return a live
NodeList object containing all the elements in the
document, in tree order, that have all the classes
specified in that argument, having obtained the classes by splitting a string on
spaces. (Duplicates are ignored.) If there are no tokens
specified in the argument, then the method must return an empty
NodeList. If the document is in quirks
mode, then the comparisons for the classes must be done in an
ASCII case-insensitive manner, otherwise, the
comparisons must be done in a case-sensitive manner. A
new NodeList object must be returned each time unless
the argument is the same as the last time the method was invoked on
this Document object, in which case the object must be
the same as the object returned by the previous call.
The getElementsByClassName(classNames) method on the
HTMLElement interface must return a live
NodeList with the nodes that the
HTMLDocument getElementsByClassName()
method would return when passed the same argument(s), excluding any
elements that are not descendants of the HTMLElement
object on which the method was invoked. A new NodeList
object must be returned each time unless the argument is the same as
the last time the method was invoked on this
HTMLElement object, in which case the object must be
the same as the object returned by the previous call.
HTML, SVG, and MathML elements define which classes they are in
by having an attribute with no namespace with the name class containing a space-separated list of classes
to which the element belongs. Other specifications may also allow
elements in their namespaces to be labeled as being in specific
classes.
Given the following XHTML fragment:
<div id="example"> <p id="p1" class="aaa bbb"/> <p id="p2" class="aaa ccc"/> <p id="p3" class="bbb ccc"/> </div>
A call to
document.getElementById('example').getElementsByClassName('aaa')
would return a NodeList with the two paragraphs
p1 and p2 in it.
A call to getElementsByClassName('ccc bbb')
would only return one node, however, namely p3. A call
to
document.getElementById('example').getElementsByClassName('bbb ccc ')
would return the same thing.
A call to getElementsByClassName('aaa,bbb') would
return no nodes; none of the elements above are in the "aaa,bbb"
class.
The HTMLDocument interface supports named properties. The names
of the supported named properties at any moment consist of
the values of the name content
attributes of all the applet, embed,
form, iframe, img, and
fallback-free object elements in the
Document that have name
content attributes, and the values of the id content attributes of all the
applet and fallback-free
object elements in the Document that have
id content attributes, and the values
of the id content attributes of all the
img elements in the Document that have
both name content attributes and
id content attributes.
When the
HTMLDocument object is indexed for property
retrieval using a name name, then the user
agent must return the value obtained using the following steps:
Let elements be the list of named elements with
the name name in the Document.
There will be at least one such element, by definition.
If elements has only one element, and that
element is an iframe element, then return the
WindowProxy object of the nested browsing
context represented by that iframe element,
and abort these steps.
Otherwise, if elements has only one element, return that element and abort these steps.
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:
applet, embed, form,
iframe, img, or
fallback-free object elements that have a
name content attribute whose value
is name, orapplet or fallback-free
object 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 name content attribute present also.An object element is said to be
fallback-free if it has no object or
embed descendants.
The dir
attribute on the HTMLDocument interface is defined
along with the dir content
attribute.
Status: Last call for comments
XML documents can be created from script using the
createDocument()
method on the DOMImplementation interface.
HTML documents can be created using the createHTMLDocument()
method:
[Supplemental, NoInterfaceObject]
interface DOMHTMLImplementation {
Document createHTMLDocument(in DOMString title);
};
DOMImplementation implements DOMHTMLImplementation;implementation . createHTMLDocument( title )Returns a new Document, with a basic DOM already
constructed with an appropriate title element.
The createHTMLDocument(title) method, when invoked, must run the
following steps:
Let doc be a newly created
Document object.
Mark doc as being an HTML document.
Create a DocumentType node with the name attribute set to the string "html", and the other attributes specific to
DocumentType objects set to the empty string, null,
and empty lists, as appropriate. Append the newly created node to
doc.
Create an html element, and append it to doc.
Create a head element, and append it to the
html element created in the previous step.
Create a title element, and append it to the
head element created in the previous step.
Create a Text node, and set its data attribute to the string given by the method's
argument (which could be the empty string). Append it to the
title element created in the previous step.
Create a body element, and append it to the
html element created in the earlier step.
Return doc.
Status: Last call for comments
Status: Last call for comments. ISSUE-41 (Decentralized-extensibility) blocks progress to Last Call
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.
Authors must not use elements, attributes, or attribute values for purposes other than their appropriate intended semantic purpose. Authors must not use elements, attributes, or attribute values that are not permitted by this specification or other applicable specifications.
For example, the following document is non-conforming, despite being syntactically correct:
<!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="http://example.org/~ernest/"><cite>Ernest</cite></a>,
in an essay from 1992
</td>
</tr>
</table>
</body>
</html>
...because the data placed in the cells is clearly not tabular
data (and the cite element mis-used). 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="http://example.org/~ernest/">Ernest</a>, in an essay from 1992 </p> </body> </html>
This next document fragment, intended to represent the heading of a corporate site, is similarly 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>ABC Company</h1> <h2>Leading the way in widget design since 1432</h2> ...
The hgroup element is intended for these kinds of
situations:
<body> <hgroup> <h1>ABC Company</h1> <h2>Leading the way in widget design since 1432</h2> </hgroup> ...
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>
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.
Status: Last call for comments
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.
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.
interface HTMLElement : Element {
// DOM tree accessors
NodeList getElementsByClassName(in DOMString classNames);
// dynamic markup insertion
attribute DOMString innerHTML;
attribute DOMString outerHTML;
void insertAdjacentHTML(in DOMString position, in DOMString text);
// metadata attributes
attribute DOMString id;
attribute DOMString title;
attribute DOMString lang;
attribute DOMString dir;
attribute DOMString className;
readonly attribute DOMTokenList classList;
readonly attribute DOMStringMap dataset;
// user interaction
attribute boolean hidden;
void click();
void scrollIntoView();
void scrollIntoView(in boolean top);
attribute long tabIndex;
void focus();
void blur();
attribute DOMString accessKey;
readonly attribute DOMString accessKeyLabel;
attribute boolean draggable;
attribute DOMString contentEditable;
readonly attribute boolean isContentEditable;
attribute HTMLMenuElement contextMenu;
attribute DOMString spellcheck;
// command API
readonly attribute DOMString commandType;
readonly attribute DOMString label;
readonly attribute DOMString icon;
readonly attribute boolean disabled;
readonly attribute boolean checked;
// styling
readonly attribute CSSStyleDeclaration style;
// event handler IDL attributes
attribute Function onabort;
attribute Function onblur;
attribute Function oncanplay;
attribute Function oncanplaythrough;
attribute Function onchange;
attribute Function onclick;
attribute Function oncontextmenu;
attribute Function ondblclick;
attribute Function ondrag;
attribute Function ondragend;
attribute Function ondragenter;
attribute Function ondragleave;
attribute Function ondragover;
attribute Function ondragstart;
attribute Function ondrop;
attribute Function ondurationchange;
attribute Function onemptied;
attribute Function onended;
attribute Function onerror;
attribute Function onfocus;
attribute Function onformchange;
attribute Function onforminput;
attribute Function oninput;
attribute Function oninvalid;
attribute Function onkeydown;
attribute Function onkeypress;
attribute Function onkeyup;
attribute Function onload;
attribute Function onloadeddata;
attribute Function onloadedmetadata;
attribute Function onloadstart;
attribute Function onmousedown;
attribute Function onmousemove;
attribute Function onmouseout;
attribute Function onmouseover;
attribute Function onmouseup;
attribute Function onmousewheel;
attribute Function onpause;
attribute Function onplay;
attribute Function onplaying;
attribute Function onprogress;
attribute Function onratechange;
attribute Function onreadystatechange;
attribute Function onscroll;
attribute Function onseeked;
attribute Function onseeking;
attribute Function onselect;
attribute Function onshow;
attribute Function onstalled;
attribute Function onsubmit;
attribute Function onsuspend;
attribute Function ontimeupdate;
attribute Function onvolumechange;
attribute Function onwaiting;
};
interface HTMLUnknownElement : HTMLElement { };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 HTMLUnknownElement interface must be used for
HTML elements that are not defined by this
specification (or other applicable specifications).
Status: Last call for comments
The following attributes are common to and may be specified on all HTML elements (even those not defined in this specification):
accesskeyclasscontenteditablecontextmenudirdraggablehiddenidlangspellcheckstyletabindextitleThe following event handler content attributes may be specified on any HTML element:
onabortonblur*oncanplayoncanplaythroughonchangeonclickoncontextmenuondblclickondragondragendondragenterondragleaveondragoverondragstartondropondurationchangeonemptiedonendedonerror*onfocus*onformchangeonforminputoninputoninvalidonkeydownonkeypressonkeyuponload*onloadeddataonloadedmetadataonloadstartonmousedownonmousemoveonmouseoutonmouseoveronmouseuponmousewheelonpauseonplayonplayingonprogressonratechangeonreadystatechangeonscrollonseekedonseekingonselectonshowonstalledonsubmitonsuspendontimeupdateonvolumechangeonwaitingThe 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
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 XHTML 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.
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).
id attributeStatus: Last call for comments
The id attribute specifies its
element's unique identifier (ID). The
value must be unique amongst all the IDs in the element's home
subtree and must contain at least one character. The value
must not contain any space
characters.
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 fragment identifiers, as a way to target an element when scripting, and as a way to style a specific element from CSS.
If the value is not the empty string, user agents must associate
the element with the given value (exactly, including any space
characters) for the purposes of ID matching within the element's
home subtree (e.g. for selectors in CSS or for the
getElementById() method in the DOM).
Identifiers are opaque strings. Particular meanings should not be
derived from the value of the id
attribute.
This specification doesn't preclude an element having multiple
IDs, if other mechanisms (e.g. DOM Core methods) can set an
element's ID in a way that doesn't conflict with the id attribute.
title attributeStatus: Last call for comments
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; and so forth. The
value is text.
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.
lang and xml:lang attributesStatus: Last call for comments
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 code, 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.
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 XHTML, 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
look at the nearest ancestor element (including the element itself
if the node is an element) that has a lang attribute in the
XML namespace set or is an HTML element and has a lang in no namespace attribute set. That
attribute specifies the language of the node.
If both the lang attribute in no
namespace and the lang attribute in the XML
namespace are set on an element, user agents must use
the lang attribute
in the XML namespace, and the lang attribute in no namespace must be
ignored for the purposes of determining
the element's language.
If no explicit language is given for any ancestors of the node, including the root element, but there is a pragma-set default language set, then that is the language of the node.
If there is no pragma-set default language, then language information from a higher-level protocol (such as HTTP), if any, must be used as the final fallback language. In the absence of any language information, and in cases where the higher-level protocol reports multiple languages, the language of the node is unknown (the empty string).
If the resulting value is not a recognized language code, then it must be treated as an unknown language having the given language code, distinct from all other languages. For the purposes of round-tripping or communicating with other services that expect language codes, user agents should pass unknown language codes through unmodified.
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 code after all.
User agents may use the element's language to determine proper processing or rendering (e.g. in the selection of appropriate fonts or pronunciations, or for dictionary selection).
The lang IDL attribute
must reflect the lang
content attribute in no namespace.
xml:base
attribute (XML only)The xml:base attribute is
defined in XML Base. [XMLBASE]
The xml:base attribute may be
used on elements of XML documents. Authors must not
use the xml:base attribute in
HTML documents.
dir attributeStatus: Last call for comments
The dir attribute specifies the
element's text directionality. The attribute is an enumerated
attribute with the keyword ltr mapping
to the state ltr, and the keyword rtl
mapping to the state rtl. The attribute has no invalid
value default and no missing value default.
The processing of this attribute is primarily performed by the presentation layer. For example, the rendering section in this specification defines a mapping from this attribute to the CSS 'direction' and 'unicode-bidi' properties, and CSS defines rendering in terms of those properties.
The directionality of an element, which is used in
particular by the canvas element's text rendering API,
is either 'ltr' or 'rtl'. If the user agent supports CSS and the
'direction' property on this element has a computed value of either
'ltr' or 'rtl', then that is the directionality of the
element. Otherwise, if the element is being rendered,
then the directionality of the element is the
directionality used by the presentation layer, potentially
determined from the value of the dir
attribute on the element. Otherwise, if the element's dir attribute has the state ltr, the
element's directionality is 'ltr' (left-to-right); if the attribute
has the state rtl, the element's directionality is 'rtl'
(right-to-left); and otherwise, the element's directionality is the
same as its parent element, or 'ltr' if there is no parent
element.
dir [ = value ]Returns the html element's dir attribute's value, if any.
Can be set, to either "ltr" or "rtl", to replace the html element's dir attribute's value.
If there is no html element, returns the empty string and ignores new values.
The dir IDL attribute on
an element must reflect the dir content attribute of that element,
limited to only known values.
The dir IDL
attribute on HTMLDocument 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).
class attributeStatus: Last call for comments
Every HTML element may have a
class attribute specified.
The attribute, if specified, must have a value that is a set of space-separated tokens representing the various classes that the element belongs to.
The classes that an HTML
element has assigned to it consists of all the classes
returned when the value of the class
attribute is split on
spaces. (Duplicates are ignored.)
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.
style attributeStatus: Last call for comments
All HTML elements may have the style content attribute set. This is a
CSS styling attribute as defined by the CSS Styling
Attribute Syntax specification. [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 CSS styling attributes. [CSSATTR]
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 hidden attribute.)
styleReturns a CSSStyleDeclaration object for the element's style attribute.
The style IDL attribute
must return a CSSStyleDeclaration whose value
represents the declarations specified in the attribute, if
present. Mutating the CSSStyleDeclaration object must
create a style attribute on the
element (if there isn't one already) and then change its value to be
a value representing the serialized form of the
CSSStyleDeclaration object. The same object must be
returned each time. [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>
Status: Last call for comments
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 XML-compatible, and
contains no characters in the range U+0041 to U+005A (LATIN CAPITAL
LETTER A to LATIN CAPITAL LETTER Z).
All attributes 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 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 independent of the site that uses the attributes.
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.
Every HTML element may have any number of custom data attributes specified, with any value.
datasetReturns 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 object, associated with the
following algorithms, which expose these attributes on their
element:
data-" and whose
remaining characters (if any) do not include any characters in
the range U+0041 to U+005A (LATIN CAPITAL LETTER A to LATIN
CAPITAL LETTER Z), 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.SYNTAX_ERR exception and abort these
steps.data- at the front of
name.setAttribute() would have raised an
exception when setting an attribute with the name name, then this must raise the same
exception.SYNTAX_ERR exception and abort these
steps.data- at the front of
name.The same object must be returned each time.
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 capitalized in the API.
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.
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.
Status: Last call for comments
Each element in this specification has a definition that includes the following information:
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.
Status: Last call for comments
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.
As noted in the conformance and terminology
sections, for the purposes of determining if an element matches its
content model or not, CDATASection nodes in the DOM are treated as
equivalent to Text nodes, and entity reference nodes are treated as if
they were expanded in place.
The space characters are 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.
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.
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.
For example, the Atom specification defines a content element. When its type attribute has the value xhtml, the Atom specification 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'),
};
Status: Last call for comments
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:
In addition, certain elements are categorized as form-associated elements and further subcategorized to define their role in various form-related processing models.
Some elements have unique requirements and do not fit into any particular category.
Status: Last call for comments
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#">
<head>
<title>Hedral's Home Page</title>
<r:RDF>
<Person xmlns="http://www.w3.org/2000/10/swap/pim/contact#"
r:about="http://hedral.example.com/#">
<fullName>Cat Hedral</fullName>
<mailbox r:resource="mailto:hedral@damowmow.com"/>
<personalTitle>Sir</personalTitle>
</Person>
</r:RDF>
</head>
<body>
<h1>My home page</h1>
<p>I like playing with string, I guess. Sister says squirrels are fun
too so sometimes I follow her to play with them.</p>
</body>
</html>
This isn't possible in the HTML serialization, however.
Status: Last call for comments
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)articleasideaudiobbdoblockquotebrbuttoncanvascitecodecommanddatalistdeldetailsdfndivdlemembedfieldsetfigurefooterformh1h2h3h4h5h6headerhgrouphriiframeimginputinskbdkeygenlabelmapmarkmathmenumeternavnoscriptobjectoloutputppreprogressqrubysampscriptsectionselectsmallspanstrongstyle (if the scoped attribute is present)subsupsvgtabletextareatimeulvarvideoAs a general rule, elements whose content model allows any
flow content should have either at least one descendant
text node that is not inter-element
whitespace, or at least one descendant element node that is
embedded content. For the purposes of this requirement,
del elements and their descendants must not be counted
as contributing to the ancestors of the del
element.
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.
Status: Last call for comments
Sectioning content is content that defines the scope of headings and footers.
Each sectioning content element potentially has a heading and an outline. See the section on headings and sections for further details.
There are also certain elements that are sectioning roots. These are distinct from sectioning content, but they can also have an outline.
Status: Last call for comments
Heading content defines the header of a section (whether explicitly marked up using sectioning content elements, or implied by the heading content itself).
Status: Last call for comments
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.
a (if it contains only phrasing content)abbrarea (if it is a descendant of a map element)audiobbdobrbuttoncanvascitecodecommanddatalistdel (if it contains only phrasing content)dfnemembediiframeimginputins (if it contains only phrasing content)kbdkeygenlabelmap (if it contains only phrasing content)markmathmeternoscriptobjectoutputprogressqrubysampscriptselectsmallspanstrongsubsupsvgtextareatimevarvideoAs a general rule, elements whose content model allows any
phrasing content should have either at least one
descendant text node that is not inter-element
whitespace, or at least one descendant element node that is
embedded content. For the purposes of this requirement,
nodes that are descendants of del elements must not be
counted as contributing to the ancestors of the del
element.
Most 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 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 space characters).