🔗ally.query.firstTabbable

Finds the first keyboard focusable ("tabbable") element in the DOM.

🔗Description

See ally.query.focusable for an explanation on the different query strategies.

Consult the data tables what browsers consider focusable and what ally.js considers focusable in strategy: "strict" or strategy: "quick" to learn how HTML elements behave.

🔗Usage

var element = ally.query.firstTabbable({
  context: '.within-filter-selector',
  defaultToContext: 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.
ignoreAutofocus	boolean	`false`	Do not give elements with `autofocs` attribute precedence.
defaultToContext	boolean	`false`	Return the `context` element if it is focusable and no other keyboard focusable element could be found.
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

HTMLElement that is the first keyboard focusable element in the given context.

🔗Examples

🔗Example: ally.query.firstTabbable ignoring autofocus Example

ally.query.firstTabbable ignoring autofocus Example on jsbin.com

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

🔗Example: ally.query.firstTabbable Example

ally.query.firstTabbable Example on jsbin.com

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

🔗Changes

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: Google Chrome's <dialog> implementation will focus the first keyboard focusable element, even if it has [tabindex="1"], ally.js does not.

WARNING: Elements with a positive tabindex attribute (e.g. [tabindex="123"]) are ignored.

🔗Related resources

ally.query.tabbable finds all keyboard focusable elements in DOM order
ally.query.tabsequence finds all keyboard focusable elements in Sequential Navigation Focus Order