hidden
attributeStatus: Last call for comments. ISSUE-95 (hidden) blocks progress to Last Call
All HTML elements may have the hidden
content attribute set. The hidden
attribute is a boolean
attribute. When specified on an element, it indicates that
the element is not yet, or is no longer, relevant.
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 hidden
attribute must not be
used to hide content that could legitimately be shown in another
presentation. For example, it is incorrect to use hidden
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 hidden
, it is hidden from all
presentations, including, for instance, screen readers.
Elements that are not hidden
should not link to or refer to elements that are hidden
.
For example, it would be incorrect to use the href
attribute to link to a
section marked with the hidden
attribute. If the content is not applicable or relevant, then there
is no reason to link to it.
It would similarly be incorrect to use the ARIA aria-describedby
attribute to
refer to descriptions that are themselves hidden
. Hiding a section means that it
is not applicable or relevant to anyone at the current time, so
clearly it cannot be a valid description of content the user can
interact with.
Elements in a section hidden by the hidden
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.
Status: Last call for comments
click
()Acts as if the element was clicked.
Status: Last call for comments
scrollIntoView
( [ top ] )Scrolls the element into view. If the top argument is true, then the element will be scrolled to the top of the viewport, otherwise it'll be scrolled to the bottom. The default is the top.
Status: Last call for comments
Status: Last call for comments
The tabindex
content attribute specifies whether the element is focusable,
whether it can be reached using sequential focus navigation, and 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.
The tabindex
attribute, if
specified, must have a value that is a valid
integer.
Status: Last call for comments
activeElement
Returns the currently focused element.
hasFocus
()Returns true if the document has focus; otherwise, returns false.
focus
()Focuses the window. Use of this method is discouraged. Allow the user to control window focus instead.
blur
()Unfocuses the window. Use of this method is discouraged. Allow the user to control window focus instead.
Status: Last call for comments
focus
()Focuses the element.
blur
()Unfocuses the element. Use of this method is discouraged. Focus another element instead.
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.
For example, to hide the outline from links, you could use:
:link:focus, :visited:focus { outline: none; }
accesskey
attributeStatus: Last call for comments
All 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, each of which must be exactly one Unicode 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.
Status: Last call for comments
Every browsing context has a selection. The selection can be empty, and the selection can have more than one range (a disjointed selection). The user agent should allow the user to change the selection. User agents are not required to let the user select more than one range, and may collapse multiple ranges in the selection to a single range when the user interacts with the selection. (But, of course, the user agent may let the user create selections with multiple ranges.)
This one selection must be shared by all the content of the browsing context (though not by nested browsing contexts), including any editing hosts in the document. (Editing hosts that are not inside a document cannot have a selection.)
Mostly for historical reasons, in addition to the browsing
context's selection, each
textarea
and input
element has an
independent selection. These are the text field selections.
The select
element also has a selection, indicating
which items have been picked by the user. This is not discussed in
this section.
This specification does not specify how selections are presented to the user.
Status: Last call for comments
getSelection
()getSelection
()Returns the Selection
object for the window, which
stringifies to the text of the current selection.
interface Selection { readonly attribute Node anchorNode; readonly attribute long anchorOffset; readonly attribute Node focusNode; readonly attribute long focusOffset; readonly attribute boolean isCollapsed; void collapse(in Node parentNode, in long offset); void collapseToStart(); void collapseToEnd(); void selectAllChildren(in Node parentNode); void deleteFromDocument(); readonly attribute long rangeCount; Range getRangeAt(in long index); void addRange(in Range range); void removeRange(in Range range); void removeAllRanges(); stringifier DOMString (); };
The Selection
interface represents a list of
Range
objects. The first item in the list has index 0,
and the last item has index count-1, where count is the number of ranges in the list. [DOMRANGE]
All of the members of the Selection
interface are
defined in terms of operations on the Range
objects
represented by this object. These operations can raise exceptions,
as defined for the Range
interface; this can therefore
result in the members of the Selection
interface
raising exceptions as well, in addition to any explicitly called out
below.
anchorNode
Returns the element that contains the start of the selection.
Returns null if there's no selection.
anchorOffset
Returns the offset of the start of the selection relative to the element that contains the start of the selection.
Returns 0 if there's no selection.
focusNode
Returns the element that contains the end of the selection.
Returns null if there's no selection.
focusOffset
Returns the offset of the end of the selection relative to the element that contains the end of the selection.
Returns 0 if there's no selection.
isCollapsed
()Returns true if there's no selection or if the selection is empty. Otherwise, returns false.
collapse
(parentNode, offset)Replaces the selection with an empty one at the given position.
Throws a WRONG_DOCUMENT_ERR
exception if the given node is in a different document.
collapseToStart
()Replaces the selection with an empty one at the position of the start of the current selection.
Throws an INVALID_STATE_ERR
exception if there is no selection.
collapseToEnd
()Replaces the selection with an empty one at the position of the end of the current selection.
Throws an INVALID_STATE_ERR
exception if there is no selection.
selectAllChildren
(parentNode)Replaces the selection with one that contains all the contents of the given element.
Throws a WRONG_DOCUMENT_ERR
exception if the given node is in a different document.
deleteFromDocument
()Deletes the selection.
rangeCount
Returns the number of ranges in the selection.
getRangeAt
(index)Returns the given range.
Throws an INDEX_SIZE_ERR
exception if the value is out of range.
addRange
(range)Adds the given range to the selection.
removeRange
(range)Removes the given range from the selection, if the range was one of the ones in the selection.
removeAllRanges
()Removes all the ranges in the selection.
In the following document fragment, the emphasized parts indicate the selection.
<p>The cute girl likes the <cite>Oxford English Dictionary</cite>.</p>
If a script invoked window.getSelection().toString()
, the return value
would be "the Oxford English
".
Status: Last call for comments
The input
and textarea
elements define
the following members in their DOM interfaces for handling their
text selection:
void select(); attribute unsigned long selectionStart; attribute unsigned long selectionEnd; void setSelectionRange(in unsigned long start, in unsigned long end);
These methods and attributes expose and control the selection of
input
and textarea
text fields.
select
()Selects everything in the text field.
selectionStart
[ = value ]Returns the offset to the start of the selection.
Can be set, to change the start of the selection.
selectionEnd
[ = value ]Returns the offset to the end of the selection.
Can be set, to change the end of the selection.
setSelectionRange
(start, end)Changes the selection to cover the given substring.
To obtain the currently selected text, the following JavaScript suffices:
var selectionText = control.value.substring(control.selectionStart, control.selectionEnd);
Characters with no visible rendering, such as U+200D ZERO WIDTH JOINER, still count as characters. Thus, for instance, the selection can include just an invisible character, and the text insertion cursor can be placed to one side or another of such a character.
contenteditable
attributeStatus: Last call for comments
The contenteditable
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.
contentEditable
[ = value ]Returns "true
", "false
", or "inherit
", based
on the state of the contenteditable
attribute.
Can be set, to change that state.
Throws a SYNTAX_ERR
exception if the new value
isn't one of those strings.
isContentEditable
Returns true if the element is editable; otherwise, returns false.
Status: Last call for comments
designMode
[ = value ]Returns "on
" if the document is editable,
and "off
" if it isn't.
Can be set, to change the document's current state.
Status: Last call for comments
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. The false
state indicates that the element is not to be checked.
spellcheck
[ = value ]Returns "true
", "false
", or "default
", based
on the state of the spellcheck
attribute.
Can be set, to change that state.
Throws a SYNTAX_ERR
exception if the new value
isn't one of those strings.
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.