Small utility that returns an array of all* tabbable DOM nodes within a containing node.
*all has some necessary caveats, which you'll learn about by reading below.
The following are considered tabbable:
<button>
elements<input>
elements<select>
elements<textarea>
elements<a>
elements with anhref
attribute<audio>
and<video>
elements withcontrols
attributes- the first
<summary>
element directly under a<details>
element <details>
element without a<summary>
element- elements with the
[contenteditable]
attribute - anything with a non-negative
tabindex
attribute
Any of the above will not be considered tabbable, though, if any of the following are also true about it:
- has a negative
tabindex
attribute - has a
disabled
attribute - either the node itself or an ancestor of it is hidden via
display: none
(*see "Display check" below to modify this behavior) - has
visibility: hidden
style - is nested under a closed
<details>
element (with the exception of the first<summary>
element) - is an
<input type="radio">
element and a different radio in its group ischecked
If you think a node should be included in your array of tabbables but it's not, all you need to do is add tabindex="0"
to deliberately include it. (Or if it is in your array but you don't want it, you can add tabindex="-1"
to deliberately exclude it.) This will also result in more consistent cross-browser behavior. For information about why your special node might not be included, see "More details", below.
- Accurate (or, as accurate as possible & reasonable)
- No dependencies
- Small
- Fast
Basically IE9+.
Why? It uses Element.querySelectorAll() and Window.getComputedStyle().
Note: When used with any version of IE, CSS.escape needs a polyfill for tabbable to work properly with radio buttons that have name
attributes containing special characters.
npm install tabbable
Dependencies: none.
import { tabbable } from 'tabbable';
tabbable(rootNode, [options]);
Returns an array of ordered tabbable nodes (i.e. in tab order) within the rootNode
.
Summary of ordering principles:
- First include any nodes with positive
tabindex
attributes (1 or higher), ordered by ascendingtabindex
and source order. - Then include any nodes with a zero
tabindex
and any element that by default receives focus (listed above) and does not have a positivetabindex
set, in source order.
Type: Node
. Required.
Type: boolean
. Default: false
.
If set to true
, rootNode
will be included in the returned tabbable node array, if rootNode
is tabbable.
Type: full
| non-zero-area
| none
. Default: full
.
Configures how to check if an element is displayed, see "Display check" below.
import { isTabbable } from 'tabbable';
isTabbable(node, [options]);
Returns a boolean indicating whether the provided node is considered tabbable.
Type: full
| non-zero-area
| none
. Default: full
.
Configures how to check if an element is displayed, see "Display check" below.
import { isFocusable } from 'tabbable';
isFocusable(node, [options]);
Returns a boolean indicating whether the provided node is considered focusable.
All tabbable elements are focusable, but not all focusable elements are tabbable. For example, elements with tabindex="-1"
are focusable but not tabbable.
Type: full
| non-zero-area
| none
. Default: full
.
Configures how to check if an element is displayed, see "Display check" below.
import { focusable } from 'tabbable';
focusable(rootNode, [options]);
Returns an array of focusable nodes within the rootNode
, in DOM order. This will not match the order in which tabbable()
returns nodes.
Type: Node
. Required.
Type: boolean
. Default: false
.
If set to true
, rootNode
will be included in the returned focusable node array, if rootNode
is focusable.
Type: full
| non-zero-area
| none
. Default: full
.
Configures how to check if an element is displayed, see "Display check" below.
- Tabbable tries to identify elements that are reliably tabbable across (not dead) browsers. Browsers are inconsistent in their behavior, though — especially for edge-case elements like
<object>
and<iframe>
— so this means some elements that you can tab to in some browsers will be left out of the results. (To learn more about this inconsistency, see this amazing table). To provide better consistency across browsers and ensure the elements you want in your tabbables list show up there, try addingtabindex="0"
to edge-case elements that Tabbable ignores. - (Exemplifying the above ^^:) The tabbability of
<iframe>
s,<embed>
s,<object>
s,<summary>
s, and<svg>
s is inconsistent across browsers, so if you need an accurate read on one of these elements you should try giving it atabindex
. (You'll also need to pay attention to thefocusable
attribute on SVGs in IE & Edge.) But you also might not be able to get an accurate read — so you should avoid relying on it. - Radio groups have some edge cases, which you can avoid by always having a
checked
one in each group (and that is what you should usually do anyway). If there is nochecked
radio in the radio group, all of the radios will be considered tabbable. (Some browsers do this, otherwise don't — there's not consistency.) - If you're thinking, "Why not just use the right
querySelectorAll
?", you may be on to something ... but, as with most "just" statements, you're probably not. For example, a simplequerySelectorAll
approach will not figure out whether an element is hidden, and therefore not actually tabbable. (That said, if you do think Tabbable can be simplified or otherwise improved, I'd love to hear your idea.) - jQuery UI's
:tabbable
selector ignores elements with height and width of0
. I'm not sure why — because I've found that I can still tab to those elements. So I kept them in. Only elements hidden withdisplay: none
orvisibility: hidden
are left out. See "Display check" below for other options. - Although Tabbable tries to deal with positive tabindexes, you should not use positive tabindexes. Accessibility experts seem to be in (rare) unanimous and clear consent about this: rely on the order of elements in the document.
- Safari on Mac OS X does not Tab to
<a>
elements by default: you have to change a setting to get the standard behavior. Tabbable does not know whether you've changed that setting or not, so it will include<a>
elements in its list.
To reliably check if an element is tabbable/focusable, Tabbable defaults to the most reliable option to keep consistent with browser behavior, however this comes at a cost since every node needs to be validated as displayed. The full
process checks for computed display property of an element and each of the element ancestors. For this reason Tabbable offers the ability of an alternative way to check if an element is displayed (or completely opt out of the check).
The displayCheck
configuration accepts the following options:
full
: (default) Most reliably resemble browser behavior, this option checks that an element is displayed and all of his ancestors are displayed as well (Notice that this doesn't excludevisibility: hidden
or elements with zero size). This check is by far the slowest option as it might cause layout reflow.non-zero-area
: This option checks display under the assumption that elements that are not displayed have zero area (width AND height equals zero). While not keeping true to browser behavior, this option is much less intensive then thefull
option and better for accessibility as zero-size elements with focusable content are considered a strong accessibility anti-pattern.none
: This completely opts out of the display check. This option is not recommended, as it might return elements that are not displayed, and as such not tabbable/focusable and can break accessibility. Make sure you know which elements in your DOM are not displayed and can filter them out yourself before using this option.
Feedback and contributions more than welcome!
See CONTRIBUTING.
In alphabetical order:
Bryan Murphy 🐛 💻 |
David Clark 💻 🐛 🚇 |
Dependabot 🚧 |
Ido Rosenthal 🐛 💻 👀 |
Kristian Hamilton 🐛 |
Mateusz Burzyński 💻 🐛 📖 |
Stefan Cameron 💻 🐛 🚇 |
Tyler Hawkins 🔧 |
pebble2050 🐛 |