wicg-inert

What is wicg-inert?

The wicg-inert npm package provides a way to make elements inert, meaning they are removed from the tab order and cannot receive focus or be interacted with by assistive technologies. This is useful for managing focus and interaction in web applications, especially when dealing with modal dialogs, overlays, or other UI elements that should temporarily disable interaction with the rest of the page.

What are wicg-inert's main functionalities?

Make an element inert

This feature allows you to make a specific element inert, meaning it will be removed from the tab order and cannot receive focus or be interacted with by assistive technologies. This is useful for disabling parts of the UI temporarily.

document.querySelector('#myElement').inert = true;

Remove inert state from an element

This feature allows you to remove the inert state from a specific element, making it interactive and focusable again. This is useful for re-enabling parts of the UI that were previously disabled.

document.querySelector('#myElement').inert = false;

Other packages similar to wicg-inert

focus-trap

The focus-trap package provides a way to trap focus within a DOM node, ensuring that the user cannot tab out of a specific area. This is useful for managing focus within modal dialogs or other interactive components. Unlike wicg-inert, which makes elements non-interactive, focus-trap ensures that focus stays within a specified area.

a11y-dialog

The a11y-dialog package helps create accessible dialog windows. It manages focus and ensures that the dialog is the only interactive element on the page when open. While wicg-inert makes elements non-interactive, a11y-dialog focuses on creating accessible modal dialogs with proper focus management.

README

The inert attribute/property allows web authors to mark parts of the DOM tree as inert:

When a node is inert, then the user agent must act as if the node was absent for the purposes of targeting user interaction events, may ignore the node for the purposes of text search user interfaces (commonly known as "find in page"), and may prevent the user from selecting text in that node.

Furthermore, a node which is inert should also be hidden from assistive technology.

Details

• Read the Explainer.
• Read the Spec.
• Try the Demo.
• Give feedback!

Polyfill

Installation

npm install --save wicg-inert

We recommend only using versions of the polyfill that have been published to npm, rather than cloning the repo and using the source directly. This helps ensure the version you're using is stable and thoroughly tested.

If you do want to build from source, make sure you clone the latest tag!

Usage

1. Add the script to your page

    ...
    <script src="/node_modules/wicg-inert/dist/inert.min.js"></script>
  </body>
</html>

2. Toggle inert on an element

const el = document.querySelector('#my-element');
el.inert = true; // alternatively, el.setAttribute('inert', '');

Legacy Browser Support

If you want to use inert with an older browser you'll need to include additional polyfills for Map, Set, Element.prototype.matches, and Node.prototype.contains.

In accordance with the W3C's new polyfill guidance, the inert polyfill does not bundle other polyfills.

You can use a service like Polyfill.io to download only the polyfills needed by the current browser. Just add the following line to the start of your page:

<script src="https://cdn.polyfill.io/v2/polyfill.min.js?features=Map,Set,Element.prototype.matches,Node.prototype.contains"></script>

Performance and gotchas

The polyfill attempts to provide a reasonable fidelity polyfill for the inert attribute, however please note:

• It relies on mutation observers to detect the addition of the inert attribute, and to detect dynamically added content within inert subtrees. Testing for inert-ness in any way immediately after either type of mutation will therefore give inconsistent results; please allow the current task to end before relying on mutation-related changes to take effect, for example via setTimeout(fn, 0) or Promise.resolve().

  Example:

const newButton = document.createElement('button');
const inertContainer = document.querySelector('[inert]');
inertContainer.appendChild(newButton);
// Wait for the next microtask to allow mutation observers to react to the
// DOM change
Promise.resolve().then(() => {
  expect(isUnfocusable(newButton)).to.equal(true);
});

• Using the inert property, however, is synchronous.

• The polyfill will be expensive, performance-wise, compared to a native inert implementation, because it requires a fair amount of tree-walking. To mitigate this, we recommend not using inert during performance sensitive actions (like during animations or scrolling). Instead, wait till these events are complete, or consider using requestIdleCallback to set inert.

Testing

Tests are written using ES5 syntax. This is to avoid needing to transpile them for older browsers. There are a few modern features they rely upon, e.g. Array.from and Promises. These are polyfilled for the tests using Polyfill.io. For a list of polyfilled features, check out the polyfill section in karma.conf.js.

Big Thanks

Cross-browser Testing Platform and Open Source <3 Provided by Sauce Labs