ally.query.firstTabbable

September 28, 2016 · View on GitHub

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.

Throws

Examples

@@@example /api/query/first-tabbable.example-2.html

firstTabbable example

@@@

@@@example /api/query/first-tabbable.example-2.html

firstTabbable without autofocus example

@@@

Changes

Since v1.1.0 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. :::

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