This specification is like no other — it has been processed with you, the humble web developer, in mind.
The focus of this specification is readability and ease of access. Unlike the full HTML Standard, this "developer's edition" removes information that only browser vendors need know. It is automatically produced from the full specification by our build tooling, and thus always in sync with the latest developments in HTML.
To read about its conception, construction, and future, read the original press release, and the blog post about its relaunch.
Finally, feel free to contribute on GitHub to make this edition better for everyone!
hidden
attributeAll
may have the content attribute set. The attribute is a . When specified on an element, it indicates that the element is not yet, or is no longer, directly relevant to the page's current state, or that it is being used to declare content to be reused by other parts of the page as opposed to being directly accessed by the user.Because this attribute is typically implemented using CSS, it's also possible to override it using CSS. For instance, a rule that applies 'display: block' to all elements will cancel the effects of the
attribute. Authors therefore have to take care when writing their style sheets to make sure that the attribute is still styled as expected.In the following skeletal example, the attribute is used to hide the Web game's main screen until the user logs in:
<h1>The Example Game</h1> <section id="login"> <h2>Login</h2> <form> ... <!-- calls login() once the user's credentials have been checked --> </form> <script> function login() { // switch screens document.getElementById('login').hidden = true; document.getElementById('game').hidden = false; } </script> </section> <section id="game" hidden> ... </section>
The
attribute must not be used to hide content that could legitimately be shown in another presentation. For example, it is incorrect to use to hide panels in a tabbed dialog, because the tabbed interface is merely a kind of overflow presentation — one could equally well just show all the form controls in one big page with a scrollbar. It is similarly incorrect to use this attribute to hide content just from one presentation — if something is marked , it is hidden from all presentations, including, for instance, screen readers.Elements that are not themselves for
attributes of and elements that are not
themselves must similarly not refer to elements that are
. In both cases, such references would cause user
confusion.
Elements and scripts may, however, refer to elements that are
in other contexts.For example, it would be incorrect to use the
attribute to link to a section marked with the attribute. If the content is not applicable or relevant, then there is no reason to link to it.It would be fine, however, to use the ARIA
attribute to refer to descriptions that are themselves . While hiding the descriptions implies that they are not useful alone, they could be written in such a way that they are useful in the specific context of being referenced from the images that they describe.Similarly, a
element with the attribute could be used by a scripted graphics engine as an off-screen buffer, and a form control could refer to a hidden element using its attribute.Elements in a section hidden by the
attribute are still active, e.g. scripts and form controls in such sections still execute and submit respectively. Only their presentation to the user changes.This section does not define or create any content attribute named "inert". This section merely defines an abstract concept of inertness.
A node (in particular elements and text nodes) can be marked as inert. When a node is inert, then the user agent must act as if the node was absent for the purposes of targeting user interaction events, may ignore the node for the purposes of text search user interfaces (commonly known as "find in page"), and may prevent the user from selecting text in that node. User agents should allow the user to override the restrictions on search and text selection, however.
For example, consider a page that consists of just a single inert
paragraph positioned in the middle of a body
. If a user moves their pointing device
from the body
over to the inert paragraph and clicks on the paragraph,
no mouseover
event would be fired, and the mousemove
and click
events would
be fired on the body
element rather than the paragraph.
When a node is inert, it generally cannot be focused. Inert nodes that are commands will also get disabled.
While a browsing context container is marked as inert, its
nested browsing context's active document, and all nodes in that
Document
, must be marked as inert.
A Document
document is blocked by a modal dialog
subject if subject is the topmost dialog
element in
document's top layer. While document is so blocked, every node
that is connected to document, with the exception of the
subject element and its shadow-including
descendants, must be marked inert. (The elements excepted by this paragraph
can additionally be marked inert through other means; being part of a modal dialog
does not "protect" a node from being marked inert.)
The dialog
element's showModal()
method causes this mechanism to trigger, by adding the dialog
element to its node
document's top layer.
Certain elements in HTML have an activation behavior, which means that the user
can activate them. This is always caused by a click
event.
click
()Acts as if the element was clicked.
An HTML user interface typically consists of multiple interactive widgets, such as form controls, scrollable regions, links, dialog boxes, browser tabs, and so forth. These widgets form a hierarchy, with some (e.g. browser tabs, dialog boxes) containing others (e.g. links, form controls).
When interacting with an interface using a keyboard, key input is channeled from the system, through the hierarchy of interactive widgets, to an active widget, which is said to be focused.
Consider an HTML application running in a browser tab running in a graphical environment. Suppose this application had a page with some text controls and links, and was currently showing a modal dialog, which itself had a text control and a button.
The hierarchy of focusable widgets, in this scenario, would include the browser window, which would have, amongst its children, the browser tab containing the HTML application. The tab itself would have as its children the various links and text controls, as well as the dialog. The dialog itself would have as its children the text control and the button.
If the widget with focus in this example was the text control in the dialog box, then key input would be channeled from the graphical system to ① the Web browser, then to ② the tab, then to ③ the dialog, and finally to ④ the text control.
Keyboard events are always targeted at this focused element.
The term focusable area is used to refer to regions of the interface that can become the target of keyboard input. Focusable areas can be elements, parts of elements, or other regions managed by the user agent.
Each focusable area has a DOM anchor, which is a Node
object
that represents the position of the focusable area in the DOM. (When the focusable
area is itself a Node
, it is its own DOM anchor.) The DOM anchor is
used in some APIs as a substitute for the focusable area when there is no other DOM object
to represent the focusable area.
The following table describes what objects can be focusable areas. The cells in the left column describe objects that can be focusable areas; the cells in the right column describe the DOM anchors for those elements. (The cells that span both columns are non-normative examples.)
Focusable area | DOM anchor |
---|---|
Examples | |
Elements that have their tabindex focus flag set, that are not actually disabled, that are not expressly inert, and that are either being rendered or being used as relevant canvas fallback content. | The element itself. |
| |
The shapes of area elements in an image map associated with an
img element that is being rendered and is not expressly
inert.
|
The img element.
|
In the following example, the <map id=wallmap><area alt="Enter Door" coords="10,10,100,200" href="door.html"></map> ... <img src="images/innerwall.jpeg" alt="There is a white wall here, with a door." usemap="#wallmap"> ... <img src="images/outerwall.jpeg" alt="There is a red wall here, with a door." usemap="#wallmap"> | |
The user-agent provided subwidgets of elements that are being rendered and are not actually disabled or expressly inert. | The element for which the focusable area is a subwidget. |
The controls in the user
interface that is exposed to the user for a | |
The scrollable regions of elements that are being rendered and are not expressly inert. | The element for which the box that the scrollable region scrolls was created. |
The CSS 'overflow' property's 'scroll' value typically creates a scrollable region. | |
The viewport of a Document that has a browsing context and is not inert.
|
The Document for which the viewport was created.
|
The contents of an | |
Any other element or part of an element, especially to aid with accessibility or to better match platform conventions. | The element. |
A user agent could make all list item bullets focusable, so that a user can more easily navigate lists. Similarly, a user agent could make all elements with |
A browsing context container (e.g. an
iframe
) is a focusable area, but key events routed to a browsing context
container get immediately routed to the nested browsing context's active
document. Similarly, in sequential focus navigation a browsing context
container essentially acts merely as a placeholder for its nested browsing
context's active document.
The following create control groups:
Document
object that have browsing
contexts.dialog
elements that have an open
attribute specified and that are being rendered.The corresponding Document
object or dialog
element is the created
control group's owner object. (There
is always a 1-to-1 mapping of control groups to control group owner objects.)
Each focusable area belongs to a single control group as follows. If the DOM anchor of a focusable area is a control group owner object, then that focusable area belongs to that control group owner object's control group. Otherwise, the focusable area belongs to its DOM anchor's nearest ancestor control group owner object's control group.
Thus:
A viewport always belongs to the control group of the
Document
for which the viewport was created.
An input
control belongs to the control group of its nearest
ancestor dialog
or Document
.
An image map's shapes belong to the nearest ancestor dialog
or
Document
of the img
elements (not the area
elements
— this means one area
element might create multiple shapes in different
control groups).
It is possible for a control group to be empty, i.e. for it to have no focusable areas.
An element is expressly inert if it is inert and its nearest ancestor control group owner object is not inert.
In a page with no dialog
elements, all elements that are inert are
expressly inert, and vice-versa.
Inside an inert dialog
element, all descendant elements are not
expressly inert, even if they are inert.
A dialog
element is expressly inert if it is inert and
not nested inside another inert dialog.
Each control group owner object can also act as the manager of a dialog group.
Each dialog
element that has an open
attribute specified and that is being rendered (i.e. that is a control group
owner object) and is not expressly inert
belongs to the dialog group whose manager is
the dialog
element's nearest ancestor control group owner object.
If no dialog
element has a particular control group owner object as
its nearest ancestor control group owner object, then that control group owner
object has no dialog group.
Each dialog group can have a dialog
designated as the focused
dialog of the dialog group. Which dialog
is so designated changes over time,
based on algorithms in this specification.
Elements in dialog groups are ordered in tree order.
One focusable area in each non-empty control group is designated the focused area of the control group. Which control is so designated changes over time, based on algorithms in this specification. If a control group is empty, it has no focused area.
Focusable areas in control groups are ordered relative to the tree order of their DOM anchors. Focusable areas with the same DOM anchor in a control group are ordered relative to their CSS box's relative positions in a pre-order, depth-first traversal of the box tree. [CSS]
The currently focused area of a top-level browsing context at any particular time is
the focusable area or dialog
returned by this algorithm:
Let candidate be the Document
of the top-level
browsing context.
If candidate has a dialog group with a designated focused dialog of the dialog group, then let candidate be the designated focused dialog of the dialog group, and redo this step.
Otherwise, if candidate has a non-empty control group, and the designated focused area of the control group is a browsing context container with a non-null nested browsing context, then let candidate be the active document of that browsing context container's nested browsing context, and redo this step.
Otherwise, if candidate has a non-empty control group, let candidate be the designated focused area of the control group.
Return candidate.
An element that is the DOM anchor of a focusable area is said to gain focus when that focusable area becomes the currently focused area of a top-level browsing context. When an element is the DOM anchor of a focusable area of the currently focused area of a top-level browsing context, it is focused.
tabindex
attributeThe tabindex
content attribute allows authors to
indicate that an element is supposed to be focusable, and
whether it is supposed to be reachable using sequential focus navigation and, if so,
what is to be the relative order of the element for the purposes of sequential focus navigation.
The name "tab index" comes from the common use of the "tab" key to navigate through the focusable
elements. The term "tabbing" refers to moving forward through the focusable elements that can be
reached using sequential focus navigation.
When the attribute is omitted, the user agent applies defaults. (There is no way to make an element that is being rendered be not focusable at all without disabling it or making it inert.)
The tabindex
attribute, if specified, must have a value
that is a valid integer. Positive numbers specify the relative position of the
element's focusable areas in the sequential focus
navigation order, and negative numbers indicate that the control is to be unreachable by
sequential focus navigation.
Developers should use caution when using values other than 0 or −1 for their tabindex
attributes as this is complicated to do correctly.
activeElement
Returns the deepest element in the document through which or to which key events are being routed. This is, roughly speaking, the focused element in the document.
For the purposes of this API, when a child browsing context is focused, its
browsing context container is focused in the
parent browsing context. For example, if the user moves the focus to a text control
in an iframe
, the iframe
is the element returned by the activeElement
API in the iframe
's
node document.
hasFocus
()Returns true if key events are being routed through or to the document; otherwise, returns false. Roughly speaking, this corresponds to the document, or a document nested inside this one, being focused.
focus
()Moves the focus to the window's browsing context, if any.
focus
()Moves the focus to the element.
If the element is a browsing context container, moves the focus to the nested browsing context instead.
blur
()Moves the focus to the viewport. Use of this method is discouraged; if you want
to focus the viewport, call the focus()
method on
the Document
's document element.
Do not use this method to hide the focus ring if you find the focus ring unsightly. Instead, use a CSS rule to override the 'outline' property, and provide a different way to show what element is focused. Be aware that if an alternative focusing style isn't made available, the page will be significantly less usable for people who primarily navigate pages using a keyboard, or those with reduced vision who use focus outlines to help them navigate the page.
For example, to hide the outline from links and instead use a yellow background to indicate focus, you could use:
:link:focus, :visited:focus { outline: none; background: yellow; color: black; }
Each element that can be activated or focused can be assigned a single key combination to
activate it, using the accesskey
attribute.
The exact shortcut is determined by the user agent, based on information about the user's
keyboard, what keyboard shortcuts already exist on the platform, and what other shortcuts have
been specified on the page, using the information provided in the accesskey
attribute as a guide.
In order to ensure that a relevant keyboard shortcut is available on a wide variety of input
devices, the author can provide a number of alternatives in the accesskey
attribute.
Each alternative consists of a single character, such as a letter or digit.
User agents can provide users with a list of the keyboard shortcuts, but authors are encouraged
to do so also. The accessKeyLabel
IDL attribute returns a
string representing the actual key combination assigned by the user agent.
In this example, an author has provided a button that can be invoked using a shortcut key. To support full keyboards, the author has provided "C" as a possible key. To support devices equipped only with numeric keypads, the author has provided "1" as another possibly key.
<input type=button value=Collect onclick="collect()" accesskey="C 1" id=c>
To tell the user what the shortcut key is, the author has this script here opted to explicitly add the key combination to the button's label:
function addShortcutKeyLabel(button) { if (button.accessKeyLabel != '') button.value += ' (' + button.accessKeyLabel + ')'; } addShortcutKeyLabel(document.getElementById('c'));
Browsers on different platforms will show different labels, even for the same key combination, based on the convention prevalent on that platform. For example, if the key combination is the Control key, the Shift key, and the letter C, a Windows browser might display "Ctrl+Shift+C", whereas a Mac browser might display "^⇧C", while an Emacs browser might just display "C-C". Similarly, if the key combination is the Alt key and the Escape key, Windows might use "Alt+Esc", Mac might use "⌥⎋", and an Emacs browser might use "M-ESC" or "ESC ESC".
In general, therefore, it is unwise to attempt to parse the value returned from the accessKeyLabel
IDL attribute.
accesskey
attributeAll HTML elements may have the accesskey
content attribute set. The accesskey
attribute's value is used
by the user agent as a guide for creating a keyboard shortcut that activates or focuses the
element.
If specified, the value must be an ordered set of unique space-separated tokens that are case-sensitive, each of which must be exactly one code point in length.
In the following example, a variety of links are given with access keys so that keyboard users familiar with the site can more quickly navigate to the relevant pages:
<nav> <p> <a title="Consortium Activities" accesskey="A" href="/Consortium/activities">Activities</a> | <a title="Technical Reports and Recommendations" accesskey="T" href="/TR/">Technical Reports</a> | <a title="Alphabetical Site Index" accesskey="S" href="/Consortium/siteindex">Site Index</a> | <a title="About This Site" accesskey="B" href="/Consortium/">About Consortium</a> | <a title="Contact Consortium" accesskey="C" href="/Consortium/contact">Contact</a> </p> </nav>
In the following example, the search field is given two possible access keys, "s" and "0" (in that order). A user agent on a device with a full keyboard might pick Ctrl+Alt+S as the shortcut key, while a user agent on a small device with just a numeric keypad might pick just the plain unadorned key 0:
<form action="/search"> <label>Search: <input type="search" name="q" accesskey="s 0"></label> <input type="submit"> </form>
In the following example, a button has possible access keys described. A script then tries to update the button's label to advertise the key combination the user agent selected.
<input type=submit accesskey="N @ 1" value="Compose"> ... <script> function labelButton(button) { if (button.accessKeyLabel) button.value += ' (' + button.accessKeyLabel + ')'; } var inputs = document.getElementsByTagName('input'); for (var i = 0; i < inputs.length; i += 1) { if (inputs[i].type == "submit") labelButton(inputs[i]); } </script>
On one user agent, the button's label might become "Compose (⌘N)". On another, it might become "Compose (Alt+⇧+1)". If the user agent doesn't assign a key, it will be just "Compose". The exact string depends on what the assigned access key is, and on how the user agent represents that key combination.
contenteditable
content attributeThe contenteditable
content attribute is an
enumerated attribute whose keywords are the empty string, true
,
and false
. The empty string and the true
keyword map
to the true state. The false
keyword maps to the false state.
In addition, there is a third state, the inherit state, which is the missing value default (and the invalid value default).
The true state indicates that the element is editable. The inherit state indicates that the element is editable if its parent is. The false state indicates that the element is not editable.
For example, consider a page that has a form
and a textarea
to
publish a new article, where the user is expected to write the article using HTML:
<form method=POST> <fieldset> <legend>New article</legend> <textarea name=article><p>Hello world.</p></textarea> </fieldset> <p><button>Publish</button></p> </form>
When scripting is enabled, the textarea
element could be replaced with a rich
text control instead, using the contenteditable
attribute:
<form method=POST> <fieldset> <legend>New article</legend> <textarea id=textarea name=article><p>Hello world.</p></textarea> <div id=div style="white-space: pre-wrap" hidden><p>Hello world.</p></div> <script> let textarea = document.getElementById("textarea"); let div = document.getElementById("div"); textarea.hidden = true; div.hidden = false; div.contentEditable = "true"; div.oninput = (e) => { textarea.value = div.innerHTML; }; </script> </fieldset> <p><button>Publish</button></p> </form>
Features to enable, e.g., inserting links, can be implemented using the document.execCommand()
API, or using
Selection
APIs and other DOM APIs. [EXECCOMMAND] [SELECTION] [DOM]
The contenteditable
attribute can also be used to
great effect:
<!doctype html> <html lang=en> <title>Live CSS editing!</title> <style style=white-space:pre contenteditable> html { margin:.2em; font-size:2em; color:lime; background:purple } head, title, style { display:block } body { display:none } </style>
contentEditable
[ = value ]Returns "true
", "false
", or "inherit
", based on the state of the contenteditable
attribute.
Can be set, to change that state.
Throws a "SyntaxError
" DOMException
if the new value
isn't one of those strings.
isContentEditable
Returns true if the element is editable; otherwise, returns false.
designMode
IDL attributedesignMode
[ = value ]Returns "on
" if the document is editable, and "off
" if it isn't.
Can be set, to change the document's current state. This focuses the document and resets the selection in that document.
Authors are encouraged to set the 'white-space' property on editing hosts and on markup that was originally created through these editing mechanisms to the value 'pre-wrap'. Default HTML whitespace handling is not well suited to WYSIWYG editing, and line wrapping will not work correctly in some corner cases if 'white-space' is left at its default value.
As an example of problems that occur if the default 'normal' value is used instead, consider the case of the user typing "yellow␣␣ball", with two spaces (here represented by "␣") between the words. With the editing rules in place for the default value of 'white-space' ('normal'), the resulting markup will either consist of "yellow ball" or "yellow ball"; i.e., there will be a non-breaking space between the two words in addition to the regular space. This is necessary because the 'normal' value for 'white-space' requires adjacent regular spaces to be collapsed together.
In the former case, "yellow⍽" might wrap to the next line ("⍽" being used here to represent a non-breaking space) even though "yellow" alone might fit at the end of the line; in the latter case, "⍽ball", if wrapped to the start of the line, would have visible indentation from the non-breaking space.
When 'white-space' is set to 'pre-wrap', however, the editing rules will instead simply put two regular spaces between the words, and should the two words be split at the end of a line, the spaces would be neatly removed from the rendering.
The spellcheck
attribute is an enumerated
attribute whose keywords are the empty string, true
and false
. The empty string and the true
keyword map to the
true state. The false
keyword maps to the false state. In
addition, there is a third state, the default state, which is the missing value default (and the invalid value default).
The true state indicates that the element is to have its spelling and
grammar checked. The default state indicates that the element is to act according to a
default behavior, possibly based on the parent element's own spellcheck
state, as defined below. The false state
indicates that the element is not to be checked.
spellcheck
[ = value ]Returns true if the element is to have its spelling and grammar checked; otherwise, returns false.
Can be set, to override the default and set the spellcheck
content attribute.
This specification does not define the user interface for spelling and grammar checkers. A user agent could offer on-demand checking, could perform continuous checking while the checking is enabled, or could use other interfaces.