Accessible Modal Primitive — Real Keyboard Focus Trap and Focus Restoration

<div class="demo">
  <p class="hint">Try tabbing through the page — focus never escapes the modal while it's open, and returns to this button when closed.</p>
  <button class="trigger" id="openBtn">Open modal</button>

  <div class="overlay" id="overlay">
    <div class="modal" role="dialog" aria-modal="true" aria-labelledby="modalTitle" id="modal">
      <h2 id="modalTitle">Accessible modal</h2>
      <p>Every focusable element below is reachable by Tab, and focus wraps from the last one back to the first — it never lands on the page behind this dialog.</p>

      <div class="modal-fields">
        <input type="text" placeholder="First field" />
        <input type="text" placeholder="Second field" />
        <a href="#" id="modalLink">A focusable link</a>
      </div>

      <div class="modal-actions">
        <button class="btn ghost" id="cancelBtn">Cancel</button>
        <button class="btn primary" id="confirmBtn">Confirm</button>
      </div>
    </div>
  </div>
</div>

* { box-sizing: border-box; margin: 0; padding: 0; }
body { font-family: system-ui, sans-serif; background: #f8fafc; display: flex; align-items: center; justify-content: center; min-height: 100vh; padding: 24px; flex-direction: column; gap: 14px; }

.hint { font-size: 12px; color: #94a3b8; max-width: 320px; text-align: center; }
.trigger { background: #4f46e5; color: #fff; border: none; padding: 10px 20px; border-radius: 10px; font-size: 13.5px; font-weight: 700; cursor: pointer; font-family: inherit; }
.trigger:hover { background: #4338ca; }
.trigger:focus-visible { outline: 2px solid #4f46e5; outline-offset: 2px; }

.overlay { position: fixed; inset: 0; background: rgba(15,23,42,0.5); display: none; align-items: center; justify-content: center; z-index: 50; }
.overlay.open { display: flex; }

.modal { width: 360px; max-width: calc(100vw - 40px); background: #fff; border-radius: 18px; padding: 24px; box-shadow: 0 24px 60px rgba(15,23,42,0.3); display: flex; flex-direction: column; gap: 14px; }
.modal h2 { font-size: 15.5px; font-weight: 800; color: #111827; }
.modal p { font-size: 12.5px; color: #64748b; line-height: 1.6; }

.modal-fields { display: flex; flex-direction: column; gap: 8px; }
.modal-fields input { padding: 9px 12px; border: 1.5px solid #e2e8f0; border-radius: 9px; font-size: 13px; font-family: inherit; }
.modal-fields input:focus-visible { outline: none; border-color: #6366f1; box-shadow: 0 0 0 3px rgba(99,102,241,0.15); }
.modal-fields a { font-size: 12.5px; color: #6366f1; font-weight: 600; }
.modal-fields a:focus-visible { outline: 2px solid #6366f1; outline-offset: 2px; border-radius: 3px; }

.modal-actions { display: flex; gap: 10px; margin-top: 4px; }
.btn { flex: 1; border: none; padding: 10px; border-radius: 10px; font-size: 13px; font-weight: 700; cursor: pointer; font-family: inherit; }
.btn.ghost { background: #f1f5f9; color: #334155; }
.btn.ghost:hover { background: #e2e8f0; }
.btn.primary { background: #4f46e5; color: #fff; }
.btn.primary:hover { background: #4338ca; }
.btn:focus-visible { outline: 2px solid #6366f1; outline-offset: 2px; }

const openBtn = document.getElementById('openBtn');
const overlay = document.getElementById('overlay');
const modal = document.getElementById('modal');
const cancelBtn = document.getElementById('cancelBtn');
const confirmBtn = document.getElementById('confirmBtn');

let lastFocusedBeforeOpen = null;

const FOCUSABLE_SELECTOR = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';

function getFocusableElements() {
  return Array.from(modal.querySelectorAll(FOCUSABLE_SELECTOR)).filter((el) => el.offsetParent !== null);
}

function openModal() {
  lastFocusedBeforeOpen = document.activeElement;
  overlay.classList.add('open');
  document.addEventListener('keydown', handleKeydown);

  // Move focus into the modal itself as soon as it opens, so a screen
  // reader user or keyboard user isn't left focused on a now-hidden trigger.
  const focusables = getFocusableElements();
  (focusables[0] || modal).focus();
}

function closeModal() {
  overlay.classList.remove('open');
  document.removeEventListener('keydown', handleKeydown);

  // Return focus to exactly whatever had it before the modal opened —
  // not just "the page body" — so keyboard context is fully preserved.
  if (lastFocusedBeforeOpen) lastFocusedBeforeOpen.focus();
}

function handleKeydown(e) {
  if (e.key === 'Escape') {
    closeModal();
    return;
  }

  if (e.key !== 'Tab') return;

  // The actual focus trap: intercept Tab/Shift+Tab at the boundaries of the
  // modal's own focusable elements and wrap around, instead of letting focus
  // escape to whatever is behind the modal in the page's natural tab order.
  const focusables = getFocusableElements();
  if (focusables.length === 0) return;

  const first = focusables[0];
  const last = focusables[focusables.length - 1];

  if (e.shiftKey && document.activeElement === first) {
    e.preventDefault();
    last.focus();
  } else if (!e.shiftKey && document.activeElement === last) {
    e.preventDefault();
    first.focus();
  }
}

openBtn.addEventListener('click', openModal);
cancelBtn.addEventListener('click', closeModal);
confirmBtn.addEventListener('click', closeModal);
overlay.addEventListener('click', (e) => { if (e.target === overlay) closeModal(); });