Modals, Dialogs & Toasts

Code

js/a11y.js — the focus trap

In the code column — js/a11y.js with trapFocus and hideBackground. This is the heart of the lesson.

trapFocus(container) does all three things:

Moves focus in (initialFocus?.focus()) on open.
Traps it via a Tab listener: finds the first and last focusable element; Tab on the last → wraps to the first, Shift+Tab on the first → to the last.
Restores focus: before opening it remembers document.activeElement (the button that opened it), and release() calls .focus() on it.

export function trapFocus(container, { initialFocus } = {}) {
  const previouslyFocused = document.activeElement;      // who opened us

  function onKeydown(e) {
    if (e.key !== 'Tab') return;
    const f = getFocusable(container);
    const first = f[0], last = f[f.length - 1];
    if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
    else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
  }

  container.addEventListener('keydown', onKeydown);
  (initialFocus || getFocusable(container)[0])?.focus();  // (1) move in

  return function release() {
    container.removeEventListener('keydown', onKeydown);
    previouslyFocused?.focus();                            // (3) restore
  };
}

getFocusable filters el.offsetParent !== null — it skips hidden elements (a hidden button shouldn't be a focus stop).

hideBackground(dialog) sets aria-hidden="true" on every child of body except the dialog, and returns a restore function. That way the screen reader "can't see" the background.

Tip. The returned release() / restore() functions are a clean pattern: trapFocus and hideBackground turn on a behavior and return a way to undo it. The modal just calls them on open and their returned functions on close. No global variables, no "is it still active".

a11y.js CREATE

Create this file in js/

// Accessibility helpers.
//
// The bug these fix: right now you can open a modal, press Tab, and your focus
// escapes to the page BEHIND it. A screen-reader or keyboard user then has no
// idea where they are. Every real dialog must:
//   1. move focus INTO the dialog when it opens
//   2. TRAP focus inside it while it's open
//   3. RESTORE focus to whatever opened it when it closes
// This is not optional polish — it's WCAG 2.1 (2.4.3 Focus Order, 2.1.2 No
// Keyboard Trap). Enterprise apps get audited on it.

const FOCUSABLE = [
  'a[href]', 'button:not([disabled])',
  'input:not([disabled]):not([type="hidden"])',
  'select:not([disabled])', 'textarea:not([disabled])',
  '[tabindex]:not([tabindex="-1"])',
].join(', ');

function getFocusable(container) {
  return [...container.querySelectorAll(FOCUSABLE)]
    .filter(el => el.offsetParent !== null);        // skip hidden elements
}

/** Trap focus in a container. Returns release(), which also RESTORES focus. */
export function trapFocus(container, { initialFocus } = {}) {
  const previouslyFocused = document.activeElement;  // remember who opened us

  function onKeydown(e) {
    if (e.key !== 'Tab') return;
    const focusable = getFocusable(container);
    if (focusable.length === 0) return;
    const first = focusable[0];
    const last = focusable[focusable.length - 1];

    if (e.shiftKey && document.activeElement === first) {      // Shift+Tab on first
      e.preventDefault(); last.focus();                        // → wrap to last
    } else if (!e.shiftKey && document.activeElement === last) { // Tab on last
      e.preventDefault(); first.focus();                       // → wrap to first
    }
  }

  container.addEventListener('keydown', onKeydown);
  (initialFocus || getFocusable(container)[0])?.focus();       // (1) move focus IN

  return function release() {
    container.removeEventListener('keydown', onKeydown);
    if (previouslyFocused instanceof HTMLElement) {
      previouslyFocused.focus();                               // (3) RESTORE focus
    }
  };
}

/** Hide the rest of the page from screen readers while a dialog is open. */
export function hideBackground(dialogEl) {
  const siblings = [...document.body.children].filter(el => el !== dialogEl);
  siblings.forEach(el => el.setAttribute('aria-hidden', 'true'));
  return () => siblings.forEach(el => el.removeAttribute('aria-hidden'));
}