Skip to content

ally.js

JavaScript library to help modern web applications with accessibility concerns by making accessibility simpler

# ally.query.focusable

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

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

# ally.query.focusable Example

ally.query.focusable Example on jsbin.com

play with ally.query.focusable Example on jsbin.com or open the document of ally.query.focusable Example

# ally.query.tabbable Example

ally.query.tabbable Example on jsbin.com

play with ally.query.tabbable Example on jsbin.com or open the document of ally.query.tabbable Example

# Changes

# Notes

See ally.is.focusRelevant

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

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