tabbable: Identify Tabbable DOM Nodes

Common errors

• focus-trap must have at least one tabbable node in it

  cause This error often originates from `focus-trap` (which uses `tabbable`) when the underlying `tabbable` library cannot find any tabbable elements in a JSDOM environment or due to incorrect `inert` attribute handling.
  fix Ensure your JSDOM setup is current (v26+). Verify that elements within the trapped container are not inadvertently hidden or marked `inert` in a way not supported by your browser/JSDOM version. Consider adding `tabindex="0"` to explicitly make an element tabbable if it should be.

• TypeError: Cannot read properties of undefined (reading 'getRootNode')

  cause This crash occurs when a DOM node being evaluated by `tabbable` is detached from the document, causing `isHidden()` to fail during a call to `getRootNode()`.
  fix Ensure that any DOM nodes passed to `tabbable` (or its internal functions) are attached to the document. This issue was largely fixed in `v6.1.0` to handle detached nodes more gracefully, but may still manifest in specific edge cases or older versions.

Warnings

• breaking Support for Internet Explorer (all versions) has been officially dropped. The library no longer guarantees functionality or provides fixes for IE environments.
  Fix: Migrate your application to modern browsers. If IE11 support is critical, you must use `tabbable` v5.x or earlier.
• gotcha The `inert` HTML attribute, which prevents focus and interaction, is not consistently supported across all major browsers (notably Firefox and Safari as of February 2023). While `tabbable` includes checks for `inert`, its effectiveness depends on browser-level support.
  Fix: For full compatibility and consistent behavior, consider polyfilling the `inert` attribute or implementing custom focus management for browsers that do not natively support it. Always test in target environments.
• gotcha When running in JSDOM environments, versions prior to v26 may exhibit issues with CSS selectors related to the `inert` attribute, leading to incorrect identification of tabbable nodes. `tabbable` v6.4.0 re-enabled a CSS selector fast path for `inert`.
  Fix: Upgrade JSDOM to version 26 or newer to ensure accurate `inert` attribute handling. If upgrading is not feasible, be aware that manual checks for inertness or adjustments to `displayCheck` might be necessary.
• gotcha The default `displayCheck='full'` option may inaccurately determine all nodes are hidden if the container element is not attached to the document. In such cases, `tabbable` may revert to `displayCheck='none'` behavior.
  Fix: Ensure the container element is attached to the document (e.g., `document.body.appendChild(container)`) when using `displayCheck='full'` or `displayCheck='non-zero-area'`. Alternatively, set `displayCheck='none'` explicitly if working with detached DOM nodes.
• gotcha Very old browser environments might require a polyfill for the `CSS.escape` API, especially if you have radio buttons with special characters in their `name` attributes. Without it, `tabbable` might not work correctly with such elements.
  Fix: If supporting legacy browsers, install and include a `CSS.escape` polyfill (e.g., `npm install css.escape`).

Install

• npm install tabbable npm
• yarn add tabbable yarn
• pnpm add tabbable pnpm

Imports

• tabbable
  wrong:

  const { tabbable } = require('tabbable');

  correct:

  import { tabbable } from 'tabbable';

  ESM is the recommended import style as shown in documentation, though CommonJS is also supported.
• focusable
  wrong:

  const focusable = require('tabbable').focusable;

  correct:

  import { focusable } from 'tabbable';

  Used to get all focusable elements, which includes tabbable elements and those with `tabindex="-1"`.
• getTabIndex
  wrong:

  import { getTabIndex } from 'tabbable/dist/getTabIndex';

  correct:

  import { getTabIndex } from 'tabbable';

  Introduced in v6.2.0, provides the computed tab index for an element, aligning with tabbable's internal logic.

Quickstart

Demonstrates how to find both tabbable and focusable elements within a given DOM node using the `tabbable` and `focusable` functions, and how to retrieve their `tabIndex`.

import { tabbable, focusable, getTabIndex } from 'tabbable';

// Helper to create a DOM structure for testing in a browser or JSDOM environment
function createTestDOM(htmlString) {
  const container = document.createElement('div');
  container.innerHTML = htmlString;
  // Append to body to ensure elements are considered 'attached' for visibility checks
  document.body.appendChild(container);
  return container;
}

const testHtml = `
  <div id="root-container">
    <button id="btn1">Click Me</button>
    <input type="text" placeholder="Enter text" />
    <a href="#" id="link1">A link</a>
    <span tabindex="0" id="span1">Custom tabbable</span>
    <div tabindex="-1" id="div1">Focusable but not tabbable</div>
    <button disabled id="btn2">Disabled Button</button>
    <a href="#" style="display: none;" id="link2">Hidden Link</a>
    <p>Some text</p>
    <textarea id="textarea1"></textarea>
  </div>
`;

const containerElement = createTestDOM(testHtml);

console.log('--- Tabbable elements ---');
const tabbableElements = tabbable(containerElement);
tabbableElements.forEach(el => {
  console.log(`Tabbable: ${el.outerHTML}, TabIndex: ${getTabIndex(el)}`);
});

console.log('\n--- Focusable elements (including non-tabbable) ---');
const focusableElements = focusable(containerElement);
focusableElements.forEach(el => {
  console.log(`Focusable: ${el.outerHTML}, TabIndex: ${getTabIndex(el)}`);
});

// Clean up the added DOM element
document.body.removeChild(containerElement);