This is revision 1.2852.
Status: Working draft
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. 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()
API, the document's
address is the same as the document's address of
the active document of the script's browsing
context.
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, as well as a few CSS rendering rules. [CSS]
A Document
object created by the createDocument()
API on the
DOMImplementation
object is initially an XML document, but can be made into an
HTML document by calling document.open()
on it.
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 found in the document 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 attribute DOMString title; attribute DOMString dir; attribute HTMLElement body; 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); NodeList getItems(optional in DOMString typeNames); getter any (in DOMString name); // dynamic markup insertion attribute DOMString innerHTML; HTMLDocument open(optional in DOMString type, optional in DOMString replace); WindowProxy open(in DOMString url, in DOMString name, in DOMString features, optional in 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 DOM 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.
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
URL
Returns the document's address.
referrer
Returns 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), 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
DOM 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 Document
has no browsing
context an INVALID_STATE_ERR
exception will be
thrown. If the contents are sandboxed into a unique origin, a
SECURITY_ERR
exception will be thrown.
The cookie
attribute represents the cookies of the resource.
On getting, if the document is not associated
with a browsing context then the user agent must raise
an INVALID_STATE_ERR
exception. Otherwise, if the
sandboxed origin browsing context flag was set on the
browsing context of the Document
when the
Document
was created, the user agent must raise a
SECURITY_ERR
exception. Otherwise, if the
document's address does not use a server-based naming
authority, it must return the empty string. Otherwise, it must first
obtain the storage mutex and then return the same
string as the value of the Cookie
HTTP header
it would include if fetching the resource
indicated by the document's address over HTTP, as per
RFC 2109 section 4.3.4 or later specifications, excluding HTTP-only
cookies. [RFC2109] [COOKIES]
On setting, if the document is not associated with a
browsing context then the user agent must raise an
INVALID_STATE_ERR
exception. Otherwise, if the
sandboxed origin browsing context flag was set on the
browsing context of the Document
when the
Document
was created, the user agent must raise a
SECURITY_ERR
exception. Otherwise, if the
document's address does not use a server-based naming
authority, it must do nothing. Otherwise, the user agent must
obtain the storage mutex and then act as it would when
processing cookies if it had just attempted to fetch
the document's address over HTTP, and had received a
response with a Set-Cookie
header whose value was the
specified value, as per RFC 2109 sections 4.3.1, 4.3.2, and 4.3.3 or
later specifications, but without overwriting the values of
HTTP-only cookies. [RFC2109] [COOKIES]
This specification does not define what makes an
HTTP-only cookie, and at the time of publication the editor is not
aware of any reference for HTTP-only cookies. They are a feature
supported by some Web browsers wherein an "httponly
" parameter added to the cookie string
causes the cookie to be hidden from script.
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.
lastModified
Returns the date of the last modification to the document, as
reported by the server, in the form "MM/DD/YYYY hh:mm:ss
".
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 to U+0039 DIGIT NINE representing the number in base ten, zero-padded if necessary. The year must be given as four or more digits in the range U+0030 DIGIT ZERO to U+0039 DIGIT NINE 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.
compatMode
In 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
DOM
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.
characterSet
Returns the document's character encoding.
defaultCharset
Returns what might be the user agent's default character 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
DOM 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
DOM attribute must, on getting, return the preferred MIME name of
the document's character encoding.
The defaultCharset
DOM 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.
readyState
Returns "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 called 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
DOM
attribute must, on getting, return the current document
readiness.
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.
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.
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 DOM 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 two 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 DOM 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.images
Returns an HTMLCollection
of the img
elements in the Document
.
embeds
plugins
Return an HTMLCollection
of the embed
elements in the Document
.
links
Returns an HTMLCollection
of the a
and area
elements in the Document
that have href
attributes.
forms
Return an HTMLCollection
of the form
elements in the Document
.
scripts
Return 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.
The getElementsByClassName(classNames)
method takes a string that
contains an unordered set of unique 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. 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.
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.
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.
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, and attribute values for purposes other than their appropriate intended semantic purpose. Authors must not use elements, attributes, and 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 should be used in 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.
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; // microdata attribute DOMString item; [PutForwards=value] readonly attribute DOMSettableTokenList itemprop; readonly attribute HTMLPropertyCollection properties; attribute DOMString content; attribute HTMLElement subject; // 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 DOM 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.
The following attributes are common to and may be specified on all HTML elements (even those not defined in this specification):
accesskey
class
contenteditable
contextmenu
dir
draggable
id
item
hidden
lang
itemprop
spellcheck
style
subject
tabindex
title
Unless otherwise specified, the following event handler content attributes may be specified on any HTML element:
onabort
onblur
*oncanplay
oncanplaythrough
onchange
onclick
oncontextmenu
ondblclick
ondrag
ondragend
ondragenter
ondragleave
ondragover
ondragstart
ondrop
ondurationchange
onemptied
onended
onerror
*onfocus
*onformchange
onforminput
oninput
oninvalid
onkeydown
onkeypress
onkeyup
onload
*onloadeddata
onloadedmetadata
onloadstart
onmousedown
onmousemove
onmouseout
onmouseover
onmouseup
onmousewheel
onpause
onplay
onplaying
onprogress
onratechange
onreadystatechange
onscroll
onseeked
onseeking
onselect
onshow
onstalled
onsubmit
onsuspend
ontimeupdate
onvolumechange
onwaiting
The attributes marked with an asterisk have a
different meaning when specified on body
elements as
those elements expose event handler attributes of the
Window
object with the same names.
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.
id
attributeStatus: Implemented and widely deployed
The id
attribute
represents its element's unique identifier. The value
must be unique 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: Implemented and widely deployed
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: Implemented and widely deployed
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. [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. Setting the attribute to the empty string indicates that the primary language is unknown.
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 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.
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 the root element, but there is a document-wide default language set, then that is the language of the node.
If there is no document-wide 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, the default value is unknown (the empty string).
If the resulting value is not a recognized language code, then it must be treated as an unknown language (as if the value was the empty string).
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
DOM 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: Implemented and widely deployed
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
defaults.
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
DOM attribute on
an element must reflect the dir
content attribute of that element,
limited to only known values.
The dir
DOM
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 an unordered set of unique 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.
Assigning classes to an element affects class
matching in selectors in CSS, the getElementsByClassName()
method in the DOM, and other such features.
Authors may use any value in the class
attribute, but are encouraged to use
the values that describe the nature of the content, rather than
values that describe the desired presentation of the
content.
style
attributeStatus: Implemented and widely deployed
All HTML elements may have the style
content attribute set. If specified,
the attribute must contain only a list of zero or more
semicolon-separated (;) CSS declarations. [CSS]
In user agents that support CSS, the attribute's value must be parsed when the attribute is added or has its value changed, with its value treated as the body (the part inside the curly brackets) of a declaration block in a rule whose selector matches just the element on which the attribute is set. All URLs in the value must be resolved relative to the element when the attribute is parsed. For the purposes of the CSS cascade, the attribute must be considered to be a 'style' attribute at the author level.
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.)
style
Returns a CSSStyleDeclaration
object for the element's style
attribute.
The style
DOM 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. [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 .. U+005A (LATIN CAPITAL
LETTER A .. LATIN CAPITAL LETTER Z).
All attributes in HTML documents get lowercased automatically, so the restriction on 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.
dataset
Returns a DOMStringMap
object for the element's data-*
attributes.
The dataset
DOM
attribute provides convenient accessors for all the data-*
attributes on an element. On
getting, the dataset
DOM attribute
must return a DOMStringMap
object, associated with the
following algorithms, which expose these attributes on their
element:
data-
", add a
name-value pair to list whose name is the
attribute's name with the first five character removed and whose
value is the attribute's value.data-
and the name passed to the
algorithm.setAttribute()
would have raised an
exception when setting an attribute with the name name, then this must raise the same
exception.data-
and the name passed to the
algorithm.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-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.id].fire()"> Fire </button> </div>
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.
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.
All the elements in this specification have a defined content model, which describes what nodes are allowed inside the elements, and thus what the structure of an HTML document or fragment must look like.
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 matches its 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 elements in the HTML namespace anywhere except where they are explicitly allowed, as defined for each element, or as explicitly required by other specifications. For XML compound documents, these contexts could be inside elements from other namespaces, if those elements are defined as providing the relevant contexts.
The Atom specification defines the Atom content
element, when its type
attribute has the value xhtml
, as requiring that it contains 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, elements in the HTML namespace 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'), };
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.
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.
Most elements that are used in the body of documents and applications are categorized as flow content.
a
abbr
address
area
(if it is a descendant of a map
element)article
aside
audio
b
bdo
blockquote
br
button
canvas
cite
code
command
datalist
del
details
dfn
dialog
div
dl
em
embed
fieldset
figure
footer
form
h1
h2
h3
h4
h5
h6
header
hgroup
hr
i
iframe
img
input
ins
kbd
keygen
label
link
(if the itemprop
attribute is present)map
mark
math
menu
meta
(if the itemprop
attribute is present)meter
nav
noscript
object
ol
output
p
pre
progress
q
ruby
samp
script
section
select
small
span
strong
style
(if the scoped
attribute is present)sub
sup
svg
table
textarea
time
ul
var
video
As 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.
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.
Heading content defines the header of a section (whether explicitly marked up using sectioning content elements, or implied by the heading content itself).
Phrasing content is the text of the document, as well as elements that mark up that text at the intra-paragraph level. Runs of phrasing content form paragraphs.
a
(if it contains only phrasing content)abbr
area
(if it is a descendant of a map
element)audio
b
bdo
br
button
canvas
cite
code
command
datalist
del
(if it contains only phrasing content)dfn
em
embed
i
iframe
img
input
ins
(if it contains only phrasing content)kbd
keygen
label
link
(if the itemprop
attribute is present)map
(if it contains only phrasing content)mark
math
meta
(if the itemprop
attribute is present)meter
noscript
object
output
progress
q
ruby
samp
script
select
small
span
strong
sub
sup
svg
textarea
time
var
video
As 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).