Declaring a context menu

The contextmenu attribute gives the element's context menu. The value must be the ID of a menu element in the same home subtree whose type attribute is in the popup menu state.

When a user right-clicks on an element with a contextmenu attribute, the user agent will first fire a contextmenu event at the element, and then, if that event is not canceled, a show event at the menu element.

<form name="npc">
 <label>Character name: <input name=char type=text contextmenu=namemenu required></label>
 <menu type=popup id=namemenu>
  <menuitem label="Pick random name" onclick="document.forms.npc.elements.char.value = getRandomName()">
  <menuitem label="Prefill other fields based on name" onclick="prefillFields(document.forms.npc.elements.char.value)">
 </menu>
</form>

Processing model

Each element has an assigned context menu, which can be null. If an element A has a contextmenu attribute, and there is an element with the ID given by A's contextmenu attribute's value in A's home subtree, and the first such element in tree order is a menu element whose type attribute is in the popup menu state, then A's assigned context menu is that element. Otherwise, if A has a parent element, then A's assigned context menu is the assigned context menu of its parent element. Otherwise, A's assigned context menu is null.

When an element's context menu is requested (e.g. by the user right-clicking the element, or pressing a context menu key), the user agent must apply the appropriate rules from the following list:

If the user requested a context menu using a pointing device

The user agent must fire a trusted event with the name contextmenu, that bubbles and is cancelable, and that uses the MouseEvent interface, at the element for which the menu was requested. The context information of the event must be initialised to the same values as the last MouseEvent user interaction event that was fired as part of the gesture that was interpreted as a request for the context menu.

Otherwise

The user agent must fire a synthetic mouse event named contextmenu that bubbles and is cancelable at the element for which the menu was requested.

Typically, therefore, the firing of the contextmenu event will be the default action of a mouseup or keyup event. The exact sequence of events is UA-dependent, as it will vary based on platform conventions.

The default action of the contextmenu event depends on whether or not the element for which the menu was requested has a non-null assigned context menu when the event dispatch has completed, as follows.

If the assigned context menu of the element for which the menu was requested is null, the default action must be for the user agent to show its default context menu, if it has one.

Otherwise, let subject be the element for which the menu was requested, and let menu be the assigned context menu of target immediately after the contextmenu event's dispatch has completed. The user agent must fire a trusted event with the name show at menu, using the RelatedEvent interface, with the relatedTarget attribute initialised to subject. The event must be cancelable.

If this event (the show event) is not canceled, then the user agent must build and show the menu for menu with subject as the subject.

The user agent may also provide access to its default context menu, if any, with the context menu shown. For example, it could merge the menu items from the two menus together, or provide the page's context menu as a submenu of the default menu. In general, user agents are encouraged to de-emphasise their own contextual menu items, so as to give the author's context menu the appearance of legitimacy — to allow documents to feel like "applications" rather than "mere Web pages".

User agents may provide means for bypassing the context menu processing model, ensuring that the user can always access the UA's default context menus. For example, the user agent could handle right-clicks that have the Shift key depressed in such a way that it does not fire the contextmenu event and instead always shows the default context menu.

The contextMenu IDL attribute must reflect the contextmenu content attribute.

<img src="cats.jpeg" alt="Cats" contextmenu=catsmenu>
<menu type="popup" id="catsmenu">
 <menuitem label="Pet the kittens" onclick="kittens.pet()">
 <menuitem label="Cuddle with the kittens" onclick="kittens.cuddle()">
 <menu label="Feed the kittens">
  <menuitem label="Fish" onclick="kittens.feed(fish)">
  <menuitem label="Chicken" onclick="kittens.feed(chicken)">
 </menu>
</menu>

The RelatedEvent interfaces

[Constructor(DOMString type, optional RelatedEventInit eventInitDict)]
interface RelatedEvent : Event {
  readonly attribute EventTarget? relatedTarget;
};

dictionary RelatedEventInit : EventInit {
  EventTarget? relatedTarget;
};

event . relatedTarget

Returns the other event target involved in this event. For example, when a show event fires on a menu element, the other event target involved in the event would be the element for which the menu is being shown.

The relatedTarget attribute must return the value it was initialised to. When the object is created, this attribute must be initialised to null. It represents the other event target that is related to the event.

Facets

A command is the abstraction behind menu items, buttons, and links. Once a command is defined, other parts of the interface can refer to the same command, allowing many access points to a single feature to share facets such as the Disabled State.

Commands are defined to have the following facets:

Type

The kind of command: "command", meaning it is a normal command; "radio", meaning that triggering the command will, amongst other things, set the Checked State to true (and probably uncheck some other commands); or "checkbox", meaning that triggering the command will, amongst other things, toggle the value of the Checked State.

ID

The name of the command, for referring to the command from the markup or from script. If a command has no ID, it is an anonymous command.

Label

The name of the command as seen by the user.

Hint

A helpful or descriptive string that can be shown to the user.

Icon

An absolute URL identifying a graphical image that represents the action. A command might not have an Icon.

Access Key

A key combination selected by the user agent that triggers the command. A command might not have an Access Key.

Hidden State

Whether the command is hidden or not (basically, whether it should be shown in menus).

Disabled State

Whether the command is relevant and can be triggered or not.

Checked State

Whether the command is checked or not.

Action

The actual effect that triggering the command will have. This could be a scripted event handler, a URL to which to navigate, or a form submission.

These facets are exposed on elements using the command API:

element . commandType

Exposes the Type facet of the command.

element . id

Exposes the ID facet of the command.

element . commandLabel

Exposes the Label facet of the command.

element . title

Exposes the Hint facet of the command.

element . commandIcon

Exposes the Icon facet of the command.

element . accessKeyLabel

Exposes the Access Key facet of the command.

element . commandHidden

Exposes the Hidden State facet of the command.

element . commandDisabled

Exposes the Disabled State facet of the command.

element . commandChecked

Exposes the Checked State facet of the command.

element . click()

Triggers the Action of the command.

The commandType attribute must return a string whose value is either "command", "radio", or "checkbox", depending on whether the Type of the command defined by the element is "command", "radio", or "checkbox" respectively. If the element does not define a command, it must return null.

The commandLabel attribute must return the command's Label, or null if the element does not define a command or does not specify a Label.

The commandIcon attribute must return the absolute URL of the command's Icon. If the element does not specify an icon, or if the element does not define a command, then the attribute must return null.

The commandHidden attribute must return true if the command's Hidden State is that the command is hidden, and false if the command is not hidden. If the element does not define a command, the attribute must return null.

The commandDisabled attribute must return true if the command's Disabled State is that the command is disabled, and false if the command is not disabled. This attribute is not affected by the command's Hidden State. If the element does not define a command, the attribute must return null.

The commandChecked attribute must return true if the command's Checked State is that the command is checked, and false if it is that the command is not checked. If the element does not define a command, the attribute must return null.

The ID facet is exposed by the id IDL attribute, the Hint facet is exposed by the title IDL attribute, and the AccessKey facet is exposed by the accessKeyLabel IDL attribute.

document . commands

Returns an HTMLCollection of the elements in the Document that define commands and have IDs.

The commands attribute of the document's Document interface must return an HTMLCollection rooted at the Document node, whose filter matches only elements that define commands and have IDs.

User agents may expose the commands that match the following criteria:

• The Hidden State facet is false (visible)
• The element is in a Document that has an associated browsing context.
• Neither the element nor any of its ancestors has a hidden attribute specified.
• The element is not a menuitem element, or it is a child of a currently relevant menu element, or it has an Access Key.

User agents are encouraged to do this especially for commands that have Access Keys, as a way to advertise those keys to the user.

For example, such commands could be listed in the user agent's menu bar.

Using the a element to define a command

An a element with an href attribute defines a command.

The Type of the command is "command".

The ID of the command is the value of the id attribute of the element, if the attribute is present and not empty. Otherwise the command is an anonymous command.

The Label of the command is the string given by the element's textContent IDL attribute.

The Hint of the command is the value of the title attribute of the element. If the attribute is not present, the Hint is the empty string.

The Icon of the command is the absolute URL obtained from resolving the value of the src attribute of the first img element descendant of the element in tree order, relative to that element, if there is such an element and resolving its attribute is successful. Otherwise, there is no Icon for the command.

The AccessKey of the command is the element's assigned access key, if any.

The Hidden State of the command is true (hidden) if the element has a hidden attribute, and false otherwise.

The Disabled State facet of the command is true if the element or one of its ancestors is inert, and false otherwise.

The Checked State of the command is always false. (The command is never checked.)

The Action of the command, if the element has a defined activation behaviour, is to run synthetic click activation steps on the element. Otherwise, it is just to fire a click event at the element.

Using the button element to define a command

A button element always defines a command.

The Type, ID, Label, Hint, Icon, Access Key, Hidden State, Checked State, and Action facets of the command are determined as for a elements (see the previous section).

The Disabled State of the command is true if the element or one of its ancestors is inert, or if the element's disabled state is set, and false otherwise.

Using the input element to define a command

An input element whose type attribute is in one of the Submit Button, Reset Button, Image Button, Button, Radio Button, or Checkbox states defines a command.

The Type of the command is "radio" if the type attribute is in the Radio Button state, "checkbox" if the type attribute is in the Checkbox state, and "command" otherwise.

The ID of the command is the value of the id attribute of the element, if the attribute is present and not empty. Otherwise the command is an anonymous command.

The Label of the command depends on the Type of the command:

If the Type is "command", then it is the string given by the value attribute, if any, and a UA-dependent, locale-dependent value that the UA uses to label the button itself if the attribute is absent.

Otherwise, the Type is "radio" or "checkbox". If the element is a labeled control, the textContent of the first label element in tree order whose labeled control is the element in question is the Label (in DOM terms, this is the string given by element.labels[0].textContent). Otherwise, the value of the value attribute, if present, is the Label. Otherwise, the Label is the empty string.

The Hint of the command is the value of the title attribute of the input element. If the attribute is not present, the Hint is the empty string.

If the element's type attribute is in the Image Button state, and the element has a src attribute, and that attribute's value can be successfully resolved relative to the element, then the Icon of the command is the absolute URL obtained from resolving that attribute that way. Otherwise, there is no Icon for the command.

The AccessKey of the command is the element's assigned access key, if any.

The Hidden State of the command is true (hidden) if the element has a hidden attribute, and false otherwise.

The Disabled State of the command is true if the element or one of its ancestors is inert, or if the element's disabled state is set, and false otherwise.

The Checked State of the command is true if the command is of Type "radio" or "checkbox" and the element is checked attribute, and false otherwise.

The Action of the command, if the element has a defined activation behaviour, is to run synthetic click activation steps on the element. Otherwise, it is just to fire a click event at the element.

Using the option element to define a command

An option element with an ancestor select element and either no value attribute or a value attribute that is not the empty string defines a command.

The Type of the command is "radio" if the option's nearest ancestor select element has no multiple attribute, and "checkbox" if it does.

The ID of the command is the value of the id attribute of the element, if the attribute is present and not empty. Otherwise the command is an anonymous command.

The Label of the command is the value of the option element's label attribute, if there is one, or else the value of option element's textContent IDL attribute, with leading and trailing whitespace stripped, and with any sequences of two or more space characters replaced by a single U+0020 SPACE character.

The Hint of the command is the string given by the element's title attribute, if any, and the empty string if the attribute is absent.

There is no Icon for the command.

The AccessKey of the command is the element's assigned access key, if any.

The Hidden State of the command is true (hidden) if the element has a hidden attribute, and false otherwise.

The Disabled State of the command is true if the element is disabled, or if its nearest ancestor select element is disabled, or if it or one of its ancestors is inert, and false otherwise.

The Checked State of the command is true (checked) if the element's selectedness is true, and false otherwise.

The Action of the command depends on its Type. If the command is of Type "radio" then it must pick the option element. Otherwise, it must toggle the option element.

Using the menuitem element to define a command

A menuitem element that does not have a command attribute defines a command.

The Type of the command is "radio" if the menuitem's type attribute is "radio", "checkbox" if the attribute's value is "checkbox", and "command" otherwise.

The ID of the command is the value of the id attribute of the element, if the attribute is present and not empty. Otherwise the command is an anonymous command.

The Label of the command is the value of the element's label attribute, if there is one, or the empty string if it doesn't.

The Hint of the command is the string given by the element's title attribute, if any, and the empty string if the attribute is absent.

The Icon for the command is the absolute URL obtained from resolving the value of the element's icon attribute, relative to the element, if it has such an attribute and resolving it is successful. Otherwise, there is no Icon for the command.

The AccessKey of the command is the element's assigned access key, if any.

The Hidden State of the command is true (hidden) if the element has a hidden attribute, and false otherwise.

The Disabled State of the command is true if the element or one of its ancestors is inert, or if the element has a disabled attribute, and false otherwise.

The Checked State of the command is true (checked) if the element has a checked attribute, and false otherwise.

The Action of the command, if the element has a defined activation behaviour, is to run synthetic click activation steps on the element. Otherwise, it is just to fire a click event at the element.

Using the command attribute on menuitem elements to define a command indirectly

A menuitem element with a master command defines a command.

The Type of the command is the Type of the master command.

The ID of the command is the value of the id attribute of the element, if the attribute is present and not empty. Otherwise the command is an anonymous command.

The Label of the command is the Label of the master command.

If the element has a title attribute, then the Hint of the command is the value of that title attribute. Otherwise, the Hint of the command is the Hint of the master command.

The Icon of the command is the Icon of the master command.

The AccessKey of the command is the element's assigned access key, if any.

The Hidden State of the command is the Hidden State of the master command.

The Disabled State of the command is the Disabled State of the master command.

The Checked State of the command is the Checked State of the master command.

The Action of the command is to invoke the Action of the master command.

Using the accesskey attribute on a label element to define a command

A label element that has an assigned access key and a labeled control and whose labeled control defines a command, itself defines a command.

The Type of the command is "command".

The ID of the command is the value of the id attribute of the element, if the attribute is present and not empty. Otherwise the command is an anonymous command.

The Label of the command is the string given by the element's textContent IDL attribute.

The Hint of the command is the value of the title attribute of the element.

There is no Icon for the command.

The AccessKey of the command is the element's assigned access key.

The Hidden State, Disabled State, and Action facets of the command are the same as the respective facets of the element's labeled control.

The Checked State of the command is always false. (The command is never checked.)

Using the accesskey attribute on a legend element to define a command

A legend element that has an assigned access key and is a child of a fieldset element that has a descendant that is not a descendant of the legend element and is neither a label element nor a legend element but that defines a command, itself defines a command.

The Type of the command is "command".

The ID of the command is the value of the id attribute of the element, if the attribute is present and not empty. Otherwise the command is an anonymous command.

The Label of the command is the string given by the element's textContent IDL attribute.

The Hint of the command is the value of the title attribute of the element.

There is no Icon for the command.

The AccessKey of the command is the element's assigned access key.

The Hidden State, Disabled State, and Action facets of the command are the same as the respective facets of the first element in tree order that is a descendant of the parent of the legend element that defines a command but is not a descendant of the legend element and is neither a label nor a legend element.

The Checked State of the command is always false. (The command is never checked.)

Using the accesskey attribute to define a command on other elements

An element that has an assigned access key defines a command.

If one of the earlier sections that define elements that define commands define that this element defines a command, then that section applies to this element, and this section does not. Otherwise, this section applies to that element.

The Type of the command is "command".

The ID of the command is the value of the id attribute of the element, if the attribute is present and not empty. Otherwise the command is an anonymous command.

The Label of the command depends on the element. If the element is a labeled control, the textContent of the first label element in tree order whose labeled control is the element in question is the Label (in DOM terms, this is the string given by element.labels[0].textContent). Otherwise, the Label is the textContent of the element itself.

The Hint of the command is the value of the title attribute of the element. If the attribute is not present, the Hint is the empty string.

There is no Icon for the command.

The AccessKey of the command is the element's assigned access key.

The Hidden State of the command is true (hidden) if the element has a hidden attribute, and false otherwise.

The Disabled State of the command is true if the element or one of its ancestors is inert, and false otherwise.

The Checked State of the command is always false. (The command is never checked.)

The Action of the command is to run the following steps:

1. Run the focusing steps for the element.
2. If the element has a defined activation behaviour, run synthetic click activation steps on the element.
3. Otherwise, if the element does not have a defined activation behaviour, fire a click event at the element.

Anchor points

This section will eventually be moved to a CSS specification; it is specified here only on an interim basis until an editor can be found to own this.

The 'anchor-point' property specifies a point to which dialog boxes are to be aligned.

If the value is a <position>, the anchor point is the point given by the value, which must be interpreted relative to the element's first rendered box's margin box. Percentages must be calculated relative to the element's first rendered box's margin box (specifically, its width for the horizontal position and its height for the vertical position). [[!CSSVALUES]] [[!CSS]]

If the value is the keyword 'none', then no explicit anchor point is defined. The user agent will pick an anchor point automatically if necessary (as described in the definition of the open() method above).

Introduction

This section is non-normative.

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.

Keyboard events are always targetted at this focused element.

Data model

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.)

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

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.

Each focusable area belongs to a control group. Each control group has an owner. Control group owners are control group owner objects. The following are control group owner objects:

• Document object in browsing contexts.
• dialog elements that have an open attribute specified and that are being rendered.

Each control group owner object owns one control group (though that group might be empty).

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.

An element is expressly inert if it is inert but it is not a control group owner object and its nearest ancestor control group owner object is not inert.

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.

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.

A dialog is expressly inert if it is inert but its nearest ancestor control group owner object is not.

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.

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

Elements in dialog groups are ordered in tree order.

The currently focused area of a top-level browsing context at any particular time is the focusable area or dialog returned by this algorithm:

1. Let candidate be the Document of the top-level browsing context.

2. 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, 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.

3. 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.

The focus chain of a focusable area or control group owner object subject is the ordered list constructed as follows:

1. Let current object be subject.

2. Let output be an empty list.

3. Loop: Append current object to output.

4. If current object is an area element's shape, append that area element to output.

   Otherwise, if current object is a focusable area whose DOM anchor is an element that is not current object itself, append that DOM anchor element to output.

5. If current object is a dialog object in a dialog group, let current object be that dialog group's manager, and return to the step labeled loop.

   Otherwise, if current object is a focusable area, let current object be that focusable area's control group's owner, and return to the step labeled loop.

   Otherwise, if current object is a Document in a nested browsing context, let current object be its browsing context container, and return to the step labeled loop.

6. Return output.

   The chain starts with subject and (if subject is or can be the currently focused area of a top-level browsing context) continues up the focus hierarchy up to the Document of the top-level browsing context.

The tabindex attribute

The 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.

Each element can have a tabindex focus flag set, as defined below. This flag is a factor that contributes towards determining whether an element is a focusable area, as described in the previous section.

If the tabindex attribute is specified on an element, it must be parsed using the rules for parsing integers. The attribute's values, or lack thereof, must be interpreted as follows:

If the attribute is omitted or parsing the value returns an error

The user agent should follow platform conventions to determine if the element's tabindex focus flag is set and, if so, whether the element and any focusable areas that have the element as their DOM anchor can be reached using sequential focus navigation, and if so, what their relative position in the sequential focus navigation order is to be.

Modulo platform conventions, it is suggested that for the following elements, the tabindex focus flag be set:

• a elements that have an href attribute
• link elements that have an href attribute
• button elements
• input elements whose type attribute are not in the Hidden state
• select elements
• textarea elements
• menuitem elements
• Elements with a draggable attribute set, if that would enable the user agent to allow the user to begin a drag operations for those elements without the use of a pointing device
• Editing hosts
• Browsing context containers
• Sorting interface th elements

One valid reason to ignore the platform conventions and always allow an element to be focused (by setting its tabindex focus flag) would be if the user's only mechanism for activating an element is through a keyboard action that triggers the focused element.

If the value is a negative integer

The user agent must set the element's tabindex focus flag, but should omit the element from the sequential focus navigation order.

One valid reason to ignore the requirement that sequential focus navigation not allow the author to lead to the element would be if the user's only mechanism for moving the focus is sequential focus navigation. For instance, a keyboard-only user would be unable to click on a text field with a negative tabindex, so that user's user agent would be well justified in allowing the user to tab to the control regardless.

If the value is a zero

The user agent must set the element's tabindex focus flag, should allow the element and any focusable areas that have the element as their DOM anchor to be reached using sequential focus navigation, following platform conventions to determine the element's relative position in the sequential focus navigation order.

If the value is greater than zero

The user agent must set the element's tabindex focus flag, should allow the element and any focusable areas that have the element as their DOM anchor to be reached using sequential focus navigation, and should place the element — referenced as candidate below — and the aforementioned focusable areas in the sequential focus navigation order so that, relative to other focusable areas in the sequential focus navigation order, they are:

• before any focusable area whose DOM anchor is an element whose tabindex attribute has been omitted or whose value, when parsed, returns an error,
• before any focusable area whose DOM anchor is an element whose tabindex attribute has a value equal to or less than zero,
• after any focusable area whose DOM anchor is an element whose tabindex attribute has a value greater than zero but less than the value of the tabindex attribute on candidate,
• after any focusable area whose DOM anchor is an element whose tabindex attribute has a value equal to the value of the tabindex attribute on candidate but that is earlier in the document in tree order than candidate,
• before any focusable area whose DOM anchor is an element whose tabindex attribute has a value equal to the value of the tabindex attribute on candidate but that is later in the document in tree order than candidate, and
• before any focusable area whose DOM anchor is an element whose tabindex attribute has a value greater than the value of the tabindex attribute on candidate.

An element that has its tabindex focus flag set but does not otherwise have an activation behaviour defined has an activation behaviour that does nothing.

This means that an element that is only focusable because of its tabindex attribute will fire a click event in response to a non-mouse activation (e.g. hitting the "enter" key while the element is focused).

An element with the tabindex attribute specified is interactive content.

The tabIndex IDL attribute must reflect the value of the tabindex content attribute. Its default value is 0 for elements that are focusable and −1 for elements that are not focusable.

Processing model

The focusing steps for an object new focus target that is either a focusable area, or an element that is not a focusable area, or a browsing context, are as follows. They can optionally be run with a fallback target.

1. If new focus target is neither a dialog element that has an open attribute specified and that is being rendered (i.e. that is a control group owner object), nor a focusable area, then run the first matching set of steps from the following list:

   If new focus target is an area element with one or more shapes that are focusable areas

   Let new focus target be the shape corresponding to the first img element in tree order that uses the image map to which the area element belongs.

   If new focus target is an element with one or more scrollable regions that are focusable areas

   Let new focus target be the element's first scrollable region, according to a pre-order, depth-first traversal of the box tree. [[!CSS]]

   If new focus target is the root element of its Document

   Let new focus target be the Document's viewport.

   If new focus target is a browsing context

   Let new focus target be the browsing context's active document.

   If new focus target is a browsing context container

   Let new focus target be the browsing context container's nested browsing context's active document.

   Otherwise

   If no fallback target was specified, abort the focusing steps.

   Otherwise, let new focus target be the fallback target.

2. If new focus target is a control group owner object that is not a focusable area, but does have a dialog group, and that dialog group has a designated focused dialog, then let new focus target be the focused dialog of the dialog group, and redo this step.

   Otherwise, if new focus target is a control group owner object that is not a focusable area, and its control group is not empty, then designate new focus target as the focused area of the control group, and redo this step.

   Otherwise, if new focus target is a browsing context container, then let new focus target be the nested browsing context's active document, and redo this step.

   A dialog element can be both a control group owner object and a focusable area, if it has both an open attribute specified and a tabindex attribute specified and is being rendered.

3. If new focus target is a focusable area and its DOM anchor is inert, then abort these steps.

4. If new focus target is the currently focused area of a top-level browsing context, then abort these steps.

5. Let old chain be the focus chain of the currently focused area of the top-level browsing context in which new focus target finds itself.

6. Let new chain be the focus chain of new focus target.

7. Run the focus update steps with old chain, new chain, and new focus target respectively.

User agents must immediately run the focusing steps for a focusable area, dialog, or browsing context candidate whenever the user attempts to move the focus to candidate.

The unfocusing steps for an object old focus target that is either a focusable area or an element that is not a focusable area are as follows:

1. If old focus target is inert, then abort these steps.

2. If old focus target is an area element and one of its shapes is the currently focused area of a top-level browsing context, or, if old focus target is an element with one or more scrollable regions, and one of them is the currently focused area of a top-level browsing context, then let old focus target be that currently focused area of a top-level browsing context.

3. Let old chain be the focus chain of the currently focused area of a top-level browsing context.

4. If old focus target is not one of the entries in old chain, then abort these steps.

5. If old focus target is a dialog in a dialog group, and the dialog group manager has a non-empty control group, then let new focus target be the designated focused area of that focus group.

   Otherwise, if old focus target is a focusable area, then let new focus target be the first focusable area of its control group (if the control group owner is a Document, this will always be a viewport).

   Otherwise, let new focus target be null.

6. If new focus target is not null, then run the focusing steps for new focus target.

When the currently focused area of a top-level browsing context is somehow unfocused without another element being explicitly focused in its stead, the user agent must immediately run the unfocusing steps for that object.

The unfocusing steps do not always result in the focus changing, even when applied to the currently focused area of a top-level browsing context. For example, if the currently focused area of a top-level browsing context is a viewport, then it will usually keep its focus regardless until another focusable area is explicitly focused with the focusing steps.

When a focusable area is added to an empty control group, it must be designated the focused area of the control group.

When a dialog group is formed, if the dialog group manager has an empty control group, the first non-inert dialog in the dialog group, if any, or else the first dialog in the dialog group regardless of inertness, must be designated the focused dialog of the dialog group.

Focus fixup rule one: When the designated focused area of a control group is removed from that control group in some way (e.g. it stops being a focusable area, it is removed from the DOM, it becomes expressly inert, etc), and the control group is still not empty: designate the first non-inert focused area in that control group to be the new focused area of the control group, if any; if they are all inert, then designate the first focused area in that control group to be the new focused area of the control group regardless of inertness. If such a removal instead results in the control group being empty, then there is simply no longer a focused area of the control group.

For example, this might happen because an element is removed from its Document, or has a hidden attribute added. It might also happen to an input element when the element gets disabled.

Focus fixup rule two: When a dialog group has no designed focused dialog of the dialog group, and its dialog group manager's control group changes from being non-empty to being empty, the first non-inert dialog in the dialog group, if any, or else the first dialog in the dialog group regardless of inertness, must be designated the focused dialog of the dialog group.

Focus fixup rule three: When the designated focused dialog of a dialog group is removed from that dialog group in some way (e.g. it stops being rendered, it loses its open attribute, it becomes expressly inert, etc), and there is still a dialog group (because the dialog in question was not the last dialog in that dialog group): if the dialog group's manager's control group is non-empty, let there be no designated focused dialog of the dialog group any more; otherwise (in the case that the control group is empty), designate the first non-inert dialog in the dialog group to be the focused dialog of the dialog group, or, if they are all inert, designate the first dialog in the dialog group to be the focused dialog of the dialog group regardless of inertness.

When the currently focused area of a top-level browsing context was a focusable area but stops being a focusable area, or when it was a dialog in a dialog group and stops being part of that dialog group, or when it starts being inert, the user agent must run the following steps:

1. Let old focus target be whatever the currently focused area of the top-level browsing context was immediately before this algorithm became applicable (e.g. before the element was disabled, or the dialog was closed, or whatever caused this algorithm to run).

2. Let old chain be the focus chain of the currently focused area of the top-level browsing context at the same time.

3. Make sure that the changes implied by the focus fixup rules one, two, and three above are applied.

4. Let new focus target be the currently focused area of a top-level browsing context.

5. If old focus target and new focus target are the same, abort these steps.

6. Let new chain be the focus chain of new focus target.

7. Run the focus update steps with old chain, new chain, and new focus target respectively.

The focus update steps, given an old chain, a new chain, and a new focus target respectively, are as follows:

1. Unset the sequential focus navigation starting point.

2. If the last entry in old chain and the last entry in new chain are the same, pop the last entry from old chain and the last entry from new chain and redo this step.

3. For each entry entry in old chain, in order, run these substeps:

   1. If entry is an input element, and the change event applies to the element, and the element does not have a defined activation behaviour, and the user has changed the element's value or its list of selected files while the control was focused without committing that change, then fire a simple event that bubbles named change at the element.

   2. If entry is an element, let blur event target be entry.

      If entry is a Document object, let blur event target be that Document object's Window object.

      Otherwise, let blur event target be null.

   3. If entry is the last entry in old chain, and entry is an Element, and the last entry in new chain is also an Element, then let related blur target be the last entry in new chain. Otherwise, let related blur target be null.

   4. If blur event target is not null, fire a focus event named blur at blur event target, with related blur target as the related target.

      In some cases, e.g. if entry is an area element's shape, a scrollable region, or a viewport, no event is fired.

4. Apply any relevant platform-specific conventions for focusing new focus target. (For example, some platforms select the contents of a text field when that field is focused.)

5. For each entry entry in new chain, in reverse order, run these substeps:

   1. If entry is a dialog element: Let entry be the designated focused dialog of its dialog group.

   2. If entry is a focusable area: Designate entry as the focused area of the control group. If its control group's owner is also a dialog group manager, then let there be no designated focused dialog in that dialog group.

      It is possible for entry to be both a dialog element and a focusable area, in which case it is its own control group owner.

   3. If entry is an element, let focus event target be entry.

      If entry is a Document object, let focus event target be that Document object's Window object.

      Otherwise, let focus event target be null.

   4. If entry is the last entry in new chain, and entry is an Element, and the last entry in old chain is also an Element, then let related focus target be the last entry in old chain. Otherwise, let related focus target be null.

   5. If focus event target is not null, fire a focus event named focus at focus event target, with related focus target as the related target.

      In some cases, e.g. if entry is an area element's shape, a scrollable region, or a viewport, no event is fired.

When a user agent is required to fire a focus event named e at an element t and with a given related target r, the user agent must create a trusted FocusEvent object, initialise it to have the given name e, to not bubble, to not be cancelable, and to have the relatedTarget attribute initialised to r, the view attribute initialised to the Window object of the Document object of t, and the detail attribute initialised to 0, and must then dispatch the newly created FocusEvent object at the specified target element t.

When a key event is to be routed in a top-level browsing context, the user agent must run the following steps:

1. Let target area be the currently focused area of the top-level browsing context.

2. If target area is a focusable area, let target node be target area's DOM anchor. Otherwise, target area is a dialog; let target node be target area.

3. If target node is a Document that has a body element, then let target node be the body element of that Document.

   Otherwise, if target node is a Document that has a root element, then let target node be the root element of that Document.

4. If target node is not inert, fire the event at target node.

   It is possible for the currently focused area of a top-level browsing context to be inert, for example if a modal dialog is shown, and then that dialog element is made inert. It is likely to be the result of a logic error in the application, though.

5. If the event was not canceled, then let target area handle the key event. This might include running synthetic click activation steps for target node.

Sequential focus navigation

Each control group has a sequential focus navigation order, which orders some or all of the focusable areas in the control group relative to each other. The order in the sequential focus navigation order does not have to be related to the order in the control group itself. If a focusable area is omitted from the sequential focus navigation order of its control group, then it is unreachable via sequential focus navigation.

There can also be a sequential focus navigation starting point. It is initially unset. The user agent may set it when the user indicates that it should be moved.

For example, the user agent could set it to the position of the user's click if the user clicks on the document contents.

When the user requests that focus move from the currently focused area of a top-level browsing context to the next or previous focusable area (e.g. as the default action of pressing the tab key), or when the user requests that focus sequentially move to a top-level browsing context in the first place (e.g. from the browser's location bar), the user agent must use the following algorithm:

1. Let starting point be the currently focused area of a top-level browsing context, if the user requested to move focus sequentially from there, or else the top-level browsing context itself, if the user instead requested to move focus from outside the top-level browsing context.

2. If there is a sequential focus navigation starting point defined and it is inside starting point, then let starting point be the sequential focus navigation starting point instead.

3. Let direction be forward if the user requested the next control, and backward if the user requested the previous control.

   Typically, pressing tab requests the next control, and pressing shift+tab requests the previous control.

4. Loop: Let selection mechanism be sequential if the starting point is a browsing context or if starting point is in its control group's sequential focus navigation order.

   Otherwise, starting point is not in its control group's sequential focus navigation order; let selection mechanism be DOM.

5. Let candidate be the result of running the sequential navigation search algorithm with starting point, direction, and selection mechanism as the arguments.

6. If candidate is not null, then run the focusing steps for candidate and abort these steps.

7. Otherwise, unset the sequential focus navigation starting point.

8. If starting point is the top-level browsing context, or a focusable area in the top-level browsing context, the user agent should transfer focus to its own controls appropriately (if any), honouring direction, and then abort these steps.

   For example, if direction is backward, then the last focusable control before the browser's rendering area would be the control to focus.

   If the user agent has no focusable controls — a kiosk-mode browser, for instance — then the user agent may instead restart these steps with the starting point being the top-level browsing context itself.

9. Otherwise, starting point is a focusable area in a nested browsing context. Let starting point be that nested browsing context's browsing context container, and return to the step labeled loop.

The sequential navigation search algorithm consists of the following steps. This algorithm takes three arguments: starting point, direction, and selection mechanism.

1. Pick the appropriate cell from the following table, and follow the instructions in that cell.

   The appropriate cell is the one that is from the column whose header describes direction and from the first row whose header describes starting point and selection mechanism.

   	direction is forward	direction is backward
   starting point is a browsing context	Let candidate be the first suitable sequentially focusable area in starting point's active document's primary control group, if any; or else null	Let candidate be the last suitable sequentially focusable area in starting point's active document's primary control group, if any; or else null
   selection mechanism is DOM	Let candidate be the first suitable sequentially focusable area in the home control group following starting point, if any; or else null	Let candidate be the last suitable sequentially focusable area in the home control group preceding starting point, if any; or else null
   selection mechanism is sequential	Let candidate be the first suitable sequentially focusable area in the home sequential focus navigation order following starting point, if any; or else null	Let candidate be the last suitable sequentially focusable area in the home sequential focus navigation order preceding starting point, if any; or else null

   A suitable sequentially focusable area is a focusable area whose DOM anchor is not inert and that is in its control group's sequential focus navigation order.

   The primary control group of a control group owner object X is the control group of X if X has no dialog group or if its dialog group has no designated focused dialog of the dialog group, otherwise, it is the primary control group of X's dialog group's designated focused dialog of the dialog group.

   The home control group is the control group to which starting point belongs.

   The home sequential focus navigation order is the sequential focus navigation order to which starting point belongs.

   The home sequential focus navigation order is the home control group's sequential focus navigation order, but is only used when the starting point is in that sequential focus navigation order (when it's not, selection mechanism will be DOM).

2. If candidate is a browsing context container, then let new candidate be the result of running the sequential navigation search algorithm with candidate's nested browsing context as the first argument, direction as the second, and sequential as the third.

   If new candidate is null, then let starting point be candidate, and return to the top of this algorithm. Otherwise, let candidate be new candidate.

3. Return candidate.

Focus management APIs

document . 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 field in an iframe, the iframe is the element returned by the activeElement API in the iframe's node document.

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 documented nested inside this one, being focused.

window . focus()

Moves the focus to the window's browsing context, if any.

element . focus()

Moves the focus to the element.

If the element is a browsing context container, moves the focus to the nested browsing context instead.

element . 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 root element.

Do not use this method to hide the focus ring. Do not use any other method that hides the focus ring from keyboard users, in particular do not use a CSS rule to override the 'outline' property. Removal of the focus ring leads to serious accessibility issues for users who navigate and interact with interactive content using the keyboard.

The activeElement attribute on Document objects must return the value returned by the following steps:

1. Let candidate be the Document on which the method was invoked.

2. 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.

3. If candidate has a non-empty control group, let candidate be the designated focused area of the control group.

4. If candidate is a focusable area, let candidate be candidate's DOM anchor.

5. If candidate is a Document that has a body element, then let candidate be the body element of that Document.

   Otherwise, if candidate is a Document that has a root element, then let candidate be the root element of that Document.

   Otherwise, if candidate is a Document, then let candidate be null.

6. Return candidate.

The hasFocus() method on Document objects must return the value returned by the following steps:

1. Let target be the Document on which the method was invoked.

2. Let candidate be the Document of the top-level browsing context.

3. If candidate is target, return true and abort these steps.

4. 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, and the active document of that browsing context container's nested browsing context is target, then return true and abort these steps.

   Otherwise, if candidate has a non-empty control group, and the designated focused area of the control group is a browsing context container, then let candidate be the active document of that browsing context container's nested browsing context, and redo this step.

   Otherwise, return false and abort these steps.

The focus() method on the Window object, when invoked, must run the focusing steps with the Window object's browsing context. Additionally, if this browsing context is a top-level browsing context, user agents are encouraged to trigger some sort of notification to indicate to the user that the page is attempting to gain focus.

The blur() method on the Window object, when invoked, provides a hint to the user agent that the script believes the user probably is not currently interested in the contents of the browsing context of the Window object on which the method was invoked, but that the contents might become interesting again in the future.

User agents are encouraged to ignore calls to this blur() method entirely.

Historically, the focus() and blur() methods actually affected the system-level focus of the system widget (e.g. tab or window) that contained the browsing context, but hostile sites widely abuse this behaviour to the user's detriment.

The focus() method on elements, when invoked, must run the following algorithm:

1. If the element is marked as locked for focus, then abort these steps.

2. Mark the element as locked for focus.

3. Run the focusing steps for the element.

4. Unmark the element as locked for focus.

The blur() method, when invoked, should run the unfocusing steps for the element on which the method was called. User agents may selectively or uniformly ignore calls to this method for usability reasons.

For example, if the blur() method is unwisely being used to remove the focus ring for aesthetics reasons, the page would become unusable by keyboard users. Ignoring calls to this method would thus allow keyboard users to interact with the page.

Introduction

This section is non-normative.

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.

<input type=button value=Collect onclick="collect()"
       accesskey="C 1" id=c>

function addShortcutKeyLabel(button) {
  if (button.accessKeyLabel != '')
    button.value += ' (' + button.accessKeyLabel + ')';
}
addShortcutKeyLabel(document.getElementById('c'));

The accesskey attribute

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 that are case-sensitive, each of which must be exactly one Unicode code point in length.

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

<form action="/search">
 <label>Search: <input type="search" name="q" accesskey="s 0"></label>
 <input type="submit">
</form>

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

Processing model

An element's assigned access key is a key combination derived from the element's accesskey content attribute. Initially, an element must not have an assigned access key.

Whenever an element's accesskey attribute is set, changed, or removed, the user agent must update the element's assigned access key by running the following steps:

1. If the element has no accesskey attribute, then skip to the fallback step below.

2. Otherwise, split the attribute's value on spaces, and let keys be the resulting tokens.

3. For each value in keys in turn, in the order the tokens appeared in the attribute's value, run the following substeps:

   1. If the value is not a string exactly one Unicode code point in length, then skip the remainder of these steps for this value.

   2. If the value does not correspond to a key on the system's keyboard, then skip the remainder of these steps for this value.

   3. If the user agent can find a mix of zero or more modifier keys that, combined with the key that corresponds to the value given in the attribute, can be used as the access key, then the user agent may assign that combination of keys as the element's assigned access key and abort these steps.

4. Fallback: Optionally, the user agent may assign a key combination of its choosing as the element's assigned access key and then abort these steps.

5. If this step is reached, the element has no assigned access key.

Once a user agent has selected and assigned an access key for an element, the user agent should not change the element's assigned access key unless the accesskey content attribute is changed or the element is moved to another Document.

When the user presses the key combination corresponding to the assigned access key for an element, if the element defines a command, the command's Hidden State facet is false (visible), the command's Disabled State facet is also false (enabled), the element is in a Document that has an associated browsing context, and neither the element nor any of its ancestors has a hidden attribute specified, then the user agent must trigger the Action of the command.

User agents might expose elements that have an accesskey attribute in other ways as well, e.g. in a menu displayed in response to a specific key combination.

The accessKey IDL attribute must reflect the accesskey content attribute.

The accessKeyLabel IDL attribute must return a string that represents the element's assigned access key, if any. If the element does not have one, then the IDL attribute must return the empty string.