Accessible Modal Dialogs: Implementing Focus Traps Correctly

1. Why focus must be trapped inside the modal

As soon as a modal opens, the whole interaction surface changes for sighted mouse users: everything outside the dialog is visually dimmed or disabled through an overlay background, often also backed by pointer-events: none. Without a focus trap, though, the tab order of the underlying document remains fully intact. A keyboard user who keeps pressing Tab after opening a newsletter popup jumps invisibly through links and buttons on the background page, without knowing they are outside the visible dialog.

For screen reader users, the problem gets worse: without technical safeguards, the screen reader may read content from the background page while the dialog is open, which is completely incomprehensible, because the announced context, for example 'dialog: subscribe to newsletter', does not match what is actually being read aloud. A focus trap solves both problems at once: it constrains the tab order to the focusable elements inside the dialog and prevents focus from silently slipping into the background.

2. Correct ARIA attributes: role="dialog", aria-modal, and aria-labelledby

An accessible dialog needs at least three ARIA building blocks working together. First, role="dialog" on the wrapper element, which tells the accessibility tree this is a standalone dialog, not regular page content. Second, aria-modal="true", which explicitly signals to screen readers that content outside the dialog is not relevant while the dialog is displayed, causing modern screen readers to automatically exclude the background from navigation. Third, aria-labelledby, which points to the ID of the visible dialog heading and immediately announces what this dialog is about on open.

These three attributes do not replace a functioning focus trap, they complement it. aria-modal="true" influences screen reader navigation but does not change the actual tab order in the DOM. A dialog with perfect ARIA attributes but no JavaScript focus trap remains broken to operate for sighted keyboard users, even though screen reader users are partially protected by aria-modal.

<div x-show="open"
     role="dialog"
     aria-modal="true"
     aria-labelledby="modal-title"
     class="fixed inset-0 z-50 flex items-center justify-center">
  <div class="bg-white rounded-xl p-6 max-w-md w-full" @keydown.escape.window="close()">
    <h2 id="modal-title" class="text-lg font-semibold">Subscribe to newsletter</h2>
    <!-- dialog content -->
  </div>
</div>

3. Implementing a focus trap in Alpine.js

Hyvä relies on Alpine.js by default, which does not ship built-in focus trap behavior, but it can be retrofitted through the official @alpinejs/focus plugin. The plugin provides the x-trap directive, which, once active, automatically focuses the first focusable descendant, constrains tab order to the dialog, and returns focus on deactivation to the element that was focused before the dialog opened.

The correct binding to the modal's open state matters: x-trap="open" activates the trap as soon as the Alpine variable open becomes true, and deactivates it automatically on close. Without the plugin, the same logic would have to be implemented manually via a keydown listener that checks, on Tab and Shift+Tab, whether focus leaves the first or last focusable element in the dialog, and cycles it back in that case.

// app.js: register the Alpine focus plugin
import Alpine from 'alpinejs';
import focus from '@alpinejs/focus';

Alpine.plugin(focus);
Alpine.start();

4. Complete Hyvä modal component with x-trap

A complete implementation combines x-trap with the ARIA attributes from the previous section plus an ESC handler. It is crucial that x-trap is bound directly to the container element that encloses all focusable elements of the dialog, not to an outer overlay element that is itself not focusable.

In this example, the background is also used as a close trigger via @click.self, which is intuitive for mouse users but must never be the only close mechanism: both a visible close button and the ESC key have to exist redundantly, so keyboard users can dismiss the dialog independently of the click-on-background behavior.

<!-- Hyvä: modal.phtml, complete focus trap implementation -->
<div x-data="{ open: false }" @open-modal.window="open = true">
  <div x-show="open"
       x-trap="open"
       @click.self="open = false"
       @keydown.escape.window="open = false"
       role="dialog"
       aria-modal="true"
       aria-labelledby="modal-title"
       class="fixed inset-0 z-50 bg-black/50 flex items-center justify-center p-4">
    <div class="bg-white rounded-xl p-6 max-w-md w-full">
      <div class="flex items-center justify-between mb-4">
        <h2 id="modal-title" class="text-lg font-semibold">Subscribe to newsletter</h2>
        <button type="button" @click="open = false" aria-label="Close dialog"
                class="min-h-[24px] min-w-[24px]">
          <svg class="h-5 w-5" aria-hidden="true"><!-- X icon --></svg>
        </button>
      </div>
      <!-- form content -->
    </div>
  </div>
</div>

5. Focus restoration on close: the most commonly forgotten step

A working focus trap inside the dialog only solves half the problem. On close, focus needs to be explicitly returned to the element that originally opened the dialog, usually a button. Without this restoration, the browser defaults to resetting focus to body, meaning keyboard users have to tab through the entire page from the beginning again after closing, just to find their way back to the original position.

The Alpine focus plugin handles this restoration automatically when x-trap is used correctly, provided the trigger button was actually focused at the time of opening. If the dialog is instead opened programmatically, for example after an AJAX request without a prior button click, the original focus reference has to be stored manually and restored on close.

// Manual focus restoration for dialogs opened without a direct
// button click, e.g. after an AJAX response
function programmaticModal() {
  return {
    open: false,
    lastFocusedElement: null,
    show() {
      this.lastFocusedElement = document.activeElement;
      this.open = true;
    },
    hide() {
      this.open = false;
      this.$nextTick(() => this.lastFocusedElement?.focus());
    },
  };
}

6. The ESC key: a mandatory feature, not a nice-to-have

The ESC key as a close mechanism is not optional for keyboard users. Without it, a user first has to tab through every focusable element in the dialog to reach a close button, which is especially tedious for longer forms inside a modal. The WAI-ARIA Authoring Practices explicitly list ESC as expected keyboard behavior for the dialog pattern.

A common bug in Alpine.js implementations: the @keydown.escape listener is bound directly to the dialog element instead of to window. If focus is then on a form field inside the dialog that itself reacts to key presses, for example a native select element, the ESC event may not reliably reach the dialog element depending on the browser. Binding to @keydown.escape.window catches the event globally and works regardless of which child element currently has focus.

7. Typical bugs in Alpine.js modals within Hyvä

Four mistakes show up particularly often in Hyvä projects. First: x-trap is bound to an element that gets removed from the layout via x-show before Alpine could set the initial focus, leading to a timing bug where focus seemingly works sometimes and not other times. The fix is to bind x-trap and x-show consistently to the same condition and avoid additional delays through CSS transitions that only make the DOM visible after focusing should have happened.

Second: multiple modals present in the DOM simultaneously, several of which accidentally have x-trap active because the underlying Alpine state was not cleanly isolated per modal. Third: the mini cart slide-over, which in many Hyvä themes technically lacks role="dialog" even though it behaves like a modal and dims the background, leaving screen reader users unaware they are in a standalone context. Fourth: focus is correctly moved into the dialog on open, but to the wrong element, for example the dialog container itself instead of the first meaningful interactive element or the heading, giving screen reader users no clear entry point.

8. Avoiding nested modals and dynamic content

A second modal opened from within an already open modal, for example a confirmation prompt inside a form dialog, complicates focus trap logic considerably, because two nested traps have to be managed simultaneously, and focus restoration when closing the inner dialog has to correctly return to the outer dialog, not to the original page behind both.

Wherever possible, it is worth avoiding nested modals architecturally and instead swapping the content of the existing dialog dynamically, for example via a two-stage Alpine state instead of a second physical dialog element. This not only reduces the complexity of the focus trap logic, it also improves the screen reader experience, since only a single dialog announcement happens per interaction.

9. Test checklist for accessible modals

Six checks can be run through in every review: open the modal via keyboard and verify focus automatically jumps into the dialog. Press Tab repeatedly inside the dialog and make sure focus never escapes into the background but cycles back to the beginning at the end of the dialog. Test Shift+Tab from the first element to verify the trap also closes correctly in reverse.

Press ESC and verify the dialog closes regardless of which child element currently has focus. After closing, check whether focus reliably returns to the original trigger element. Finally, with an active screen reader, verify that the dialog heading is announced correctly on open and that background content is not read aloud while the dialog is displayed.

10. Summary

11. FAQ: Modal Focus Trap: The Essentials at a Glance