ally.query.focusable

December 30, 2016 ยท View on GitHub

Finds focusable elements in the DOM.

Description

The query infrastructure provides two different implementations. The "quick" strategy uses document.querySelectorAll and is able to find most focusable elements. Elements that are made focusable by way of CSS properties cannot be queried that way, though. To allow finding more focusable elements, the "strict" strategy makes use of TreeWalker to "manually" iterate over the DOM. While the "strict" strategy provides more accurate results, it is slower than the "quick" strategy. The default strategy is "quick".

The "all" strategy, used internally by ally.maintain.disabled will find all the elements that are either focus relevant or only tabbable - including elements that would be focusable, were they not visually hidden or disabled.

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

Usage

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

Arguments

NameTypeDefaultDescription
context<selector>documentElementThe scope of the DOM in which to search. The first element of a collection is used.
includeContextbooleanfalsePrepend the context element if it is focusable.
includeOnlyTabbablebooleanfalseInclude 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.

Throws

Examples

@@@example /api/query/focusable.example.html

focusable example

@@@

@@@example /api/query/tabbable.example.html

tabbable example

@@@

Changes

  • Since v1.1.0 the context option can point to another document (e.g. <body> in an iframe)
  • 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 Querying the DOM for focus-relevant (focusable, tabbable, only-tabbable) elements will not include elements of the documents of nested browsing contexts such as <iframe> and <object>. :::

:::warning Any element marked only-tabbable in the focusable browser compatibility tables is not identified by ally.is.focusable or ally.is.tabbable, only by ally.is.onlyTabbable. That is because these elements cannot be interacted with via script, i.e. calling element.focus() does not have any effect. :::

Contributing