🔗ally.query.tabsequence

Finds keyboard focusable ("tabbable") elements in the DOM and returns them in the order calculated based on tabindex attribute values.

🔗Description

The Sequential Navigation Focus Order depends on a variety of factors:

Value of the tabindex attribute. The sequence generally starts with all positive tabindex elements with tabindex="1" in DOM order, then all elements with tabindex="2" in DOM order, then all elements with tabindex="3", … until the highest tabindex is reached, at which point the sequence continues with the tabindex="0" (which is set implicitly for a number of HTML elements, e.g. <input>).
<area> elements may either be sorted in DOM order of the <area> itsel, or the <img> referencing the map.
Within a Shadow DOM positive tabindex elements may either be sorted localized to the ShadowRoot, or globally in the document.

ally.query.tabsequence uses ally.query.tabbable to find keyboard focusable elements and then sorts the element positions respecting Shadow DOM, <area> vs <img> replacement and tabindex attribute value.

🔗Usage

var sequence = ally.query.tabsequence({
  context: '.within-filter-selector',
  includeContext: true,
  strategy: 'quick',
});

🔗Arguments

Name	Type	Default	Description
context	`<selector>`	`documentElement`	The scope of the DOM in which to search. The first element of a collection is used.
includeContext	boolean	`false`	Prepend the `context` element if it is focusable.
includeOnlyTabbable	boolean	`false`	Include elements that would otherwise be ignored because they're considered only tabbable,
strategy	`"quick"`, `"strict"`, `"all"`	`"quick"`	The approach used to find elements.

🔗Returns

Array of HTMLElement.

🔗Examples

🔗Example: ally.query.tabsequence Example

ally.query.tabsequence Example on jsbin.com

play with the example on jsbin.com or open the source document

🔗Changes

Since v#master the module can move <area> elements to the place of the <img> elements they're referenced from.
Since v#master the module can sort elements in Shadow DOM localized to the ShadowRoot.
Since v#master the option includeOnlyTabbable allows to skip the internal filter preventing this module from returning elements that cannot be focused by script.

🔗Notes

See ally.is.focusRelevant

NOTE: In some browsers <area> elements are provided in DOM order they occur. Others provide them in DOM order of the <img> elements that use them. ally.query.tabindex handles this appropriately. See Sequential Navigation Focus Order for Image Maps, Blink 447289, WebKit 140259

NOTE: In some browsers positive tabindexes are sorted localized to Shadow DOM, in some they are sorted globally. ally.query.tabindex handles this appropriately.

WARNING: In Firefox the Flexbox CSS property order affects the tabsequence, Gecko 812687, ally.js does not replicate this behavior.

WARNING: In Firefox referencing the same <map> can lead to elements missing from the tabsequence, Gecko 1116126, ally.js does not replicate this behavior.

WARNING: In Firefox <label tabindex="0"> is part of the tabsequence, Gecko 1240285, ally.js does not replicate this behavior.

🔗Related resources

ally.is.tabbable is used to filter focusable elements
ally.query.focusable is used to find focusable elements
ally.query.firstTabbable finds the first keyboard focusable element in a context
ally.query.tabbable finds keyboard focusable elements in DOM order
HTML5: The tabindex attribute