Forem: Jan Nicklas

Focus Containment: The Broken State of Keyboard Navigation

Jan Nicklas — Thu, 22 May 2025 16:44:13 +0000

As web developers, we strive to create experiences that work for everyone.
Yet when it comes to keyboard navigation which is a critical component of web accessibility, we're still struggling with fundamental challenges.
Even the largest tech companies with substantial resources fail to deliver consistent keyboard experiences.

The central problem? Focus containment.
It's one of the most complex aspects of keyboard navigation and with the current browser APIs it feels impossible to get right.

The Importance of Keyboard Navigation

Before diving into the technical aspects, let's take a look why this matters:

Accessibility: Many users with motor disabilities rely entirely on keyboards
Power users: Keyboard shortcuts enable efficient navigation for all users
Screen reader users: Rely on consistent focus management to understand page context

A broken focus experience isn't just an inconvenience - it can render a website completely unusable for a significant portion of your audience.

Baseline

To be fair, defining a common expaction for keyboard navigation is tricky. But many users expect web content to behave as predictably as the browser UI itself. Think about it when you hit Tab while in the URL bar, you know exactly what's going to happen. Focus moves to the next element in a logical sequence, with clear visual feedback. No surprises.. it just works:

The Current State: A Case Study in Frustration

Let's look at some high-profile examples of focus management failures:

Case 1: The Disappearing Focus State

By default overlays will not contain focus which leads to a frustrating experience for keyboard users.
As you can see on Gitlab opening the search bar and then pressing tab causes focus to move completely off-screen.
The user is essentially "lost" with no visual indication of where they are in the page:

Case 2: Inconsistent Controls

Many sites use very inconsistent key controls for focus traps.
Like many other sites Mozilla's website implements focus traps that use tab keys in some components and arrow keys in others - even on the same page next to each other.

The search behaviour is different from the native browser url bar and often leads to the frustrating experience where users must guess which key to use in each context

Case 2: Unreachable Elements on Amazon, Bing and YouTube

Amazon, Bing and YouTube contain interface elements that are completely unreachable via keyboard in certain states, effectively blocking keyboard users from core functionality

If organizations with dedicated accessibility teams and substantial resources struggle with these basics, what hope do smaller teams have?

The Four Inadequate Approaches We Currently Use

1. No Solution At All

Many sites simply don't address focus containment. This results in:

Focus disappearing off-screen
Users tabbing into invisible or irrelevant areas
Complete loss of context for keyboard and screen reader users

This "solution" is really the absence of one, creating a poor experience that's unfortunately still common even on major platforms like GitLab.

2. JavaScript Focus Traps

The most common approach today involves complex JavaScript to:

Create and maintain lists of focusable elements
Handle tab/shift+tab at boundaries
Restore focus when traps are closed

But these implementations:

Are difficult to maintain
Often contain bugs
Rarely account for dynamically added content
Create inconsistent experiences across websites
Frequently fail to handle edge cases

A typical focus trap implementation requires 100+ lines of JavaScript with numerous edge cases. Here's just a small sample of what's needed:

// Simplified example - real implementations are much more complex
function createFocusTrap(element) {
  const focusableElements = element.querySelectorAll(
    'a[href], button, input, textarea, select, details, [tabindex]:not([tabindex="-1"])'
  );

  const firstElement = focusableElements[0];
  const lastElement = focusableElements[focusableElements.length - 1];

  element.addEventListener('keydown', (e) => {
    if (e.key === 'Tab') {
      if (e.shiftKey && document.activeElement === firstElement) {
        e.preventDefault();
        lastElement.focus();
      } else if (!e.shiftKey && document.activeElement === lastElement) {
        e.preventDefault();
        firstElement.focus();
      }
    }
  });
}

Even the best implementations are brittle and fail in complex scenarios.

3. The `<dialog>` Element

The <dialog> element is a step forward, providing native focus containment:

<dialog id="myDialog">
  <h2>Dialog Content</h2>
  <button id="closeDialog">Close</button>
</dialog>

<script>
  const dialog = document.getElementById('myDialog');
  dialog.showModal(); // Activates native focus containment
</script>

Benefits include:

Browser-handled focus management
Ability to access browser UI (a significant improvement)
Built-in backdrop and stacking context

But it still has critical limitations:

Inflexible single-container approach: Only works for simple dialogs
Can't handle multiple interactive layers: No way to allow focus on both a dialog and a toast notification
No simple way to create custom dialog-like components: Forces using the dialog element even when it's not semantically appropriate

4. The `inert` Attribute

The HTML inert attribute is our most powerful option today:

<header>
  <nav>Navigation here</nav>
</header>

<main>
  <section inert>This content is not interactive</section>
  <section>This content remains interactive</section>
</main>

<footer inert>Footer content here</footer>

This lets us mark specific parts of the page as non-interactive, which is a reversal of the focus trap approach. Instead of containing focus within an element, we remove interactivity from everything else.

While powerful, it has a fatal flaw: no support for "donut holes" of interactivity.

The Donut Hole Problem

Imagine a common UI pattern: a modal with a toast notification that appears on top. The modal should trap focus, but users should also be able to interact with the toast:

Or a search bar which has to be inside the header to receive focus but should also allow focus in its flyout:

With current solutions, this is nearly impossible to implement correctly:

Using <dialog>: The toast/input would be outside the dialog's focus trap, making it unreachable
Using JavaScript traps: Requires complex coordination between multiple traps
Using inert: You'd need to mark everything except the modal as inert, then somehow exempt the toast/input.. This is quite complex and has various edge cases. For example you would have to watch the entire DOM for new appearing elements

This "donut hole" problem (where you need interactive elements inside otherwise non-interactive areas) appears in various UI patterns:

Modals with toast notifications
Search overlays with interactive results
Dropdown menus with nested interactive components
Tutorial overlays with interactive elements

The Missed Opportunity: CSS `interactivity: inert`

The CSS Working Group developed a promising solution in the interactivity property draft.
https://github.com/w3c/csswg-drafts/issues/10711

And Chrome 135 has already shipped the new CSS interactivity property:

/* Make the main content inert */
main {
  interactivity: inert;
}
/* Create another "donut hole" of interactivity */
main .active-component {
  interactivity: auto;
}

This approach could revolutionise focus management by:

Making focus containment declarative rather than imperative
Allowing for nested interactive zones (solving the donut hole problem)
Separating behavior from structure
Enabling responsive focus containment through media queries

But critically, according to discussions in the draft, the working group decided to remove support for "interactive donut holes" again.

This would essentially reduce this new css property to be equivalent to the existing HTML inert attribute.
So the latest plan is going back to the status quo of the inert html attribute instead of improving APIs for authors to build better keyboard user experiences.

A Call for Change

I believe we should keep the CSS interactivity property with support for donut holes like shipped in Chrome 135.

It will help developers to solve complex focus containment problems with simpler, more declarative code.

Theoretically, you could still hack around these limitations with some creative CSS:

body:has(.active-component) *:not(:has(.active-component), .active-component) { 
  interactivity: inert; 
}   
.active-component * {   
  interactivity: auto !important;   
}

But let's be honest this is a hack.

The browser would need to recalculate styles for every single element on the page, causing FPS drops during interactions. And very often these kinds of hacks tend to become maintenance issues or buggy over time..

Why We Need Better Standards

With the current APIs before Chrome 135 web authors weren't able to fix their keyboard interactions

Current solutions have too many gaps for modern web applications
Developers need declarative ways to control focus
The "donut hole" feature is a real-world requirement
Core accessibility shouldn't require JavaScript focus hacks

What You Can Do Today

While we advocate for better standards, here are some best practices to implement today:

Use the <dialog> element when appropriate
It's not perfect, but it's better than custom JavaScript for simple modals
Leverage the inert attribute
For simple cases, this can provide good focus management
Test aggressively with keyboards
Verify that users can always see where focus is and access all functionality
Consider alternative patterns
Sometimes simplifying your UI is an option and can eliminate complex focus management needs

Conclusion

Focus containment remains one of web development's most challenging accessibility problems. The current tools force developers to choose between poor user experiences and complex, fragile implementations.

If we want a more accessible web, we need better primitives. The decision to limit the CSS interactivity property might become a missed opportunity to solve a critical problem. Let's ask for revisiting this decision and providing developers with the tools they need to create truly accessible experiences.

Because when even the biggest tech companies struggle to get this right, the problem might not be with the developers - it's probably with our tools

html-webpack-plugin 4 has been released!

Jan Nicklas — Mon, 23 Mar 2020 11:42:58 +0000

It took way too long but finally the new major version of the html-webpack-plugin is making it's leap from beta to a stable release!

Performance!

One big goal for this release was to improve the performance during development and production builds.

The performance boost was gained mainly by dropping the usage of compilation.getStats().toJson() thanks to a new API provided by the webpack core team around @sokra. This new API provides all information necessary to inject the scripts and styles into the html code.

Unfortunately relying on that API means that webpack 1-3 can not be supported anymore.

To further increase the performance the entire caching approach was rebuilt from scratch to decrease the compilation efforts.

The alpha tester feedback was great!

#953 "The best of 5 total build time goes down from 10.41s (with 4.0.0-alpha) to 10.29s - which is now only 130ms slower than when not using the plugin at all :-)"

#962: "For reference, my project (which has grown substantially since #962) builds in ~8000ms without and ~1000ms with these changes."

While working on those performance improvements I wrote a cpuprofile-webpack-plugin - a small util to analyse your webpack build performance for production build but even more importantly for recompilations during development.

// Detect dark theme var iframe = document.getElementById('tweet-1149466691627130881-19'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1149466691627130881&theme=dark" }

Feel free to give it a try and let me know what you think :)

Template language support

Since html-webpack-plugin 2.x has been able to use the loaders specified inside the webpack config file. Therefore it is not only capable of compiling .ejs templates but any code which can be transpiled with a webpack loader (hbs, ejs, twig, dust, pug, htl, js, ts, jsx, tsx ...).

A javascript or jsx template allows even to generate a static server side rendered version of your application.

html-webpack-plugin template:

import ReactDOMServer from 'react-dom/server';
import React from 'react';
import { App } from './App';

export default () => `
  <!doctype html>
    <html lang="en">
    <head>
      <meta charset="utf-8">
      <title>Server Side Rendering Demo</title>
    </head>
    <body>
      <div id="root">${ReactDOMServer.renderToString(<App />)}</div>
    </body>
    </html>
`

For further details on how to connect loaders to the html-webpack-plugin checkout the template option docs or take a look at the html-webpack-plugin jsx codesandbox.

Another way to use the html-webpack-plugin to prerender a static page out of your app is the prerender-loader from @developit.

Meta Tags

The html-webpack-plugin is now able to inject meta-tags without writing custom templates:

new HtmlWebpackPlugin({
  meta: {viewport: 'width=device-width, initial-scale=1, shrink-to-fit=no'},
})

Base Tags

Similar to the meta tags it is now also possible to add a base tag:

new HtmlWebpackPlugin({
  base: '/',
})

Custom Template with Zero Config

Customizing the template is now possible without configuration.

From version 4 the html-webpack-plugin will look for a local src/index.ejs file. If such a file can be found it will be used as a template:

Minification by default

Thanks to the work by @edmorley we were able to enable html minification by default if webpack is running in production mode. This behaviour can be disabled by adding minification: false to the html-webpack-plugin configuration.

Enable minification by default when 'mode' is production #1048

edmorley posted on Sep 16, 2018

Previously minification was disabled by default. Now, if minify is undefined and mode is 'production', then it is enabled using the following options:

{
  collapseWhitespace: true,
  removeComments: true,
  removeRedundantAttributes: true,
  removeScriptTypeAttributes: true,
  removeStyleLinkTypeAttributes: true,
  useShortDoctype: true
}

These options were based on the settings used by create-react-app, Neutrino and vue-cli, and are hopefully fairly conservative. See: https://github.com/jantimon/html-webpack-plugin/issues/1036#issuecomment-421408841 https://github.com/kangax/html-minifier#options-quick-reference

These same defaults can enabled regardless of mode, by setting minify to true (which previously passed an empty object to html-minifier, meaning most minification features were disabled). Similarly, minification can be disabled even in production, by setting minify to false.

This change has no effect on users who pass an object to minify.

Fixes #1036.

View on GitHub

Allow template variable modification

Evan You asked for a better way to modify which values are sent down to the template:

feat(template): support custom template params #830

yyx990803 posted on Jan 01, 2018

This allows the user to inject custom variables to be used in the template interpolation, e.g. simplifying webpackConfig.output.publicPath to something shorter.

Docs/tests are not included, but if this sounds like a good idea I can add those upon request.

View on GitHub

The outcome was a new templateVariables option which allows to add additional data e.g. process.env to the values which are sent down to the template:

Nonblocking script loading

Until now all script tags were added at the end of the body tag.

However now that all modern browsers allow to load javascript in parallel without pausing the html parsing the scriptLoading option can speed up your users page loads.

Usage:

new HtmlWebpackPlugin({
  scriptLoading: 'defer'
})

New Hooks

The webpack core team asked to upgrade to the new hook system to further increase the webpack build speed.

These hooks allow plugin developers to change the default behaviour of the html-webpack-plugin. The following chart shows the flow and the hooks (beforeAssetTagGeneration, alterAssetTags, alterAssetTagGroups, afterTemplateExecution, beforeEmit, afterEmit):

Here is an example for a plugin which manipulates the generated html file in the beforeEmit hook:

const HtmlWebpackPlugin = require('html-webpack-plugin');

class MyPlugin {
  apply (compiler) {
    compiler.hooks.compilation.tap('MyPlugin', (compilation) => {
      // Static Plugin interface |compilation |HOOK NAME | register listener 
      HtmlWebpackPlugin.getHooks(compilation).beforeEmit.tapAsync(
        'MyPlugin', // <-- Set a meaningful name here for stacktraces
        (data, cb) => {
          // Manipulate the content
          data.html += 'The Magic Footer'
          // Tell webpack to move on
          cb(null, data)
        }
      )
    })
  }
}

module.exports = MyPlugin

For more information please take a look at the readme events section

Contributors

People around the world are approaching me to ask for help, suggest and work on new features, fix a typo or even fix entire problems. Thank you so much and please keep it up! :)

If you have any feedback for this release create an issue or contact me on twitter @jantimon (direct messages are open).

Full changelog

The changelog with all changes can be found directly on github

What is coming up next?

The next goal is to be fully compatible with the Webpack 5. Especially with the new Webpack 5 FileSystemInfo API to solve

Webpack 5 Support Plan? #1269

septs posted on Sep 09, 2019

The webpack 5.0 changelog https://github.com/webpack/changelog-v5/blob/master/README.md

@jantimon

View on GitHub

Another goal would be to further improve browser load times. For browsers with support for preloading @sokra proposed an even faster approach than scriptLoading: 'defer'.

Forem: Jan Nicklas

Focus Containment: The Broken State of Keyboard Navigation

The Importance of Keyboard Navigation

Baseline

The Current State: A Case Study in Frustration

Case 1: The Disappearing Focus State

Case 2: Inconsistent Controls

Case 2: Unreachable Elements on Amazon, Bing and YouTube

The Four Inadequate Approaches We Currently Use

1. No Solution At All

2. JavaScript Focus Traps

3. The <dialog> Element

4. The inert Attribute

The Donut Hole Problem

The Missed Opportunity: CSS interactivity: inert

A Call for Change

Why We Need Better Standards

What You Can Do Today

Conclusion

html-webpack-plugin 4 has been released!

Performance!

Template language support

Meta Tags

Base Tags

Custom Template with Zero Config

Minification by default

Enable minification by default when 'mode' is production #1048

Allow template variable modification

feat(template): support custom template params #830

Nonblocking script loading

New Hooks

Contributors

Sponsors

Full changelog

What is coming up next?

Webpack 5 Support Plan? #1269

3. The `<dialog>` Element

4. The `inert` Attribute

The Missed Opportunity: CSS `interactivity: inert`