| layout | tags |
|---|---|
doc-api.html |
argument-options |
Finds focusable elements in the DOM.
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".
var elements = ally.query.focusable({
context: '.within-filter-selector',
includeContext: true,
strategy: 'quick',
});| 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. |
Array of HTMLElement.
@@@example /api/query/focusable.example.html
@@@
@@@example /api/query/tabbable.example.html
@@@
- Since
v1.1.0thecontextoption can point to another document (e.g.<body>in an iframe) - Since
v1.1.0the optionincludeOnlyTabbableallows to skip the internal filter preventing this module from returning elements that cannot be focused by script.
:::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.
:::
-
ally.query.firstTabbablefinds the first keyboard focusable element -
ally.query.tabbablefinds all keyboard focusable elements in DOM order -
ally.query.tabsequencefinds all keyboard focusable elements in Sequential Navigation Focus Order -
ally.is.focusableused to filter focusable elements