tabbable

<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->

<!-- ALL-CONTRIBUTORS-BADGE:END -->

Small utility that returns an array of all* tabbable DOM nodes within a containing node.

<small>*all has some necessary caveats, which you'll learn about by reading below.</small>

The following are considered tabbable:

• <button> elements
• <input> elements
• <select> elements
• <textarea> elements
• <a> elements with an href attribute
• <audio> and <video> elements with controls 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 is checked
• is a form field (button, input, select, textarea) inside a disabled <fieldset>
• is inert or in an inert container
  • ❗️ Only supported in newer browsers that support this new attribute)
  • ⚠️ Notably not (yet) supported on Firefox and Safari (Feb 2023)

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.

Goals

• Accurate (or, as accurate as possible & reasonable)
• No dependencies
• Small
• Fast

Browser Support

As old and as broad as reasonably possible, excluding browsers that are out of support or have nearly no user base.

Focused on desktop browsers, particularly Chrome, Edge, FireFox, Safari, and Opera.

Tabbable is not officially tested on any mobile browsers or devices.

⚠️ Microsoft no longer supports any version of IE, so IE is no longer supported by this library.

💬 Keep in mind that performance optimization and old browser support are often at odds, so tabbable may not always be able to use the most optimal (typically modern) APIs in all cases.

Installation

npm install tabbable

💬 Some very old browsers may need a polyfill for the CSS.escape API for tabbable to work properly with radio buttons that have name attributes containing special characters.

API

tabbable

import { tabbable } from 'tabbable';

tabbable(container, [options]);

• container: Node (Required)
• options:
  • All the common options.
  • includeContainer: boolean (default: false)
    • If set to true, container will be included in the returned tabbable node array, if container is tabbable.
    • Note that whether this option is true or false, if the container is inert, none of its children (deep) will be considered tabbable.

Returns an array of ordered tabbable nodes (i.e. in tab order) within the container.

Summary of ordering principles:

• First include any nodes with positive tabindex attributes (1 or higher), ordered by ascending tabindex 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 positive tabindex set, in source order.

isTabbable

import { isTabbable } from 'tabbable';

isTabbable(node, [options]);

• node: Node (Required)
• options:
  • All the common options.

Returns a boolean indicating whether the provided node is considered tabbable.

💬 If the node has an inert ancestor, it will not be tabbable.

focusable

import { focusable } from 'tabbable';

focusable(container, [options]);

• container: Node: Required
• options:
  • All the common options.
  • includeContainer: boolean (default: false)
    • If set to true, container will be included in the returned focusable node array, if container is focusable.
    • Note that whether this option is true or false, if the container is inert, none of its children (deep) will be considered focusable.

Returns an array of focusable nodes within the container, in DOM order. This will not match the order in which tabbable() returns nodes.

isFocusable

import { isFocusable } from 'tabbable';

isFocusable(node, [options]);

• node: Node (Required)
• options:
  • All the common 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. Also note that if the node has aninert ancestor, it will not be focusable.

getTabIndex

import { getTabIndex } from 'tabbable';

getTabIndex(node);

• node: Element (Required)

Returns a negative, 0, or positive number that expresses the node's tab index in the DOM, with exceptions made where there are browser inconsistencies related to <audio>, <video>, <details>, and elements with the contenteditable="true" attribute.

The specific exceptions may change over time. See the implementation for specific behavior.

Common Options

These options apply to all APIs.

displayCheck option

Type: full | full-native | legacy-full | non-zero-area | none . Default: full.

Configures how to check if an element is displayed.

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 using Web APIs that cause layout reflow.

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) resembles browser behavior via manual checks; this option checks that an element is displayed, which requires it to be attached to the DOM, and for all of his ancestors to be displayed (notice this doesn't exclude visibility: hidden or elements with zero size). This option will cause layout reflow, however. If that is a concern, consider the none option.
  • ⚠️ If the container given to tabbable() or focusable(), or the node given to isTabbable() or isFocusable(), is not attached to the window's main document, the node will be considered hidden and neither tabbable nor focusable. This behavior is new as of v6.0.0.
  • If your code relies on the legacy behavior where detached nodes were considered visible, and you are unable to fix your code to use tabbable once the node is attached, use the legacy-full option.
• full-native: uses the browser built-in Element#checkVisibility, with all of its options. This handles, for example, content-visibility auto states, visibility: hidden and elements with zero size.
  • If Element#checkVisibility is not supported, this strategy falls back to the full behavior.
  • While each check is specified, it is possible that browsers will disagree with each other, or not support the full set of options.
• legacy-full: Same as full but restores the legacy behavior of treating detached nodes as visible. This means that if a node is detached, it's then treated as though the display check was set to none (see below for details).
  • ❗️ Since detached nodes are not treated as tabbable/focusable by browsers, using this option is not recommended as it knowingly diverges from browser behavior.
  • ⚠️ This option may be removed in the future. Tabbable will not maintain it at the expense of new features or if having it makes the code disproportionately more complex. It only exists to make the upgrade path to the correct behavior (i.e. the full option) as long and smooth as reasonably possible.
  • The APIs used to determine a node's display are not supported unless its attached (i.e. the browser does not calculate its display unless it is attac