Focus Management Deep Dive — Advanced Focus Techniques Guide

<!-- tabindex usage patterns -->
<button>Native button — tabindex="0" implicitly</button>

<div role="button" tabindex="0" onclick="activate()">
  Custom button — tabindex="0" for Tab reachability
</div>

<div id="error-summary" role="alert" tabindex="-1" onclick="handleError()">
  Programmatic focus only — use focus() when errors appear
</div>

<!-- Roving tabindex: only one item in a group is tabbable -->
<ul role="listbox" aria-label="Scan options">
  <li role="option" tabindex="0" aria-selected="true">Quick scan</li>
  <li role="option" tabindex="-1" aria-selected="false">Full scan</li>
  <li role="option" tabindex="-1" aria-selected="false">Custom scan</li>
</ul>

function openSidePanel() {
  const mainContent = document.getElementById('main-content');
  const sidePanel = document.getElementById('side-panel');

  // Make main content inert — cannot be focused or perceived by AT
  mainContent.inert = true;
  mainContent.setAttribute('aria-hidden', 'true');

  // Open panel and focus it
  sidePanel.hidden = false;
  sidePanel.querySelector('h2').focus();
}

function closeSidePanel() {
  const mainContent = document.getElementById('main-content');
  const sidePanel = document.getElementById('side-panel');

  // Restore main content
  mainContent.inert = false;
  mainContent.removeAttribute('aria-hidden');

  // Close panel
  sidePanel.hidden = true;
  document.querySelector('[onclick="openSidePanel()"]').focus();
}

// Scroll into view only if not already visible
element.focus({ preventScroll: true });

// Focus without triggering a scroll
element.focus({ preventScroll: true });

// Focus and ensure the element is visible
element.focus({ preventScroll: false });

// Detect if element supports focus
function safeFocus(element) {
  if (element && typeof element.focus === 'function') {
    try {
      element.focus({ preventScroll: true });
      return true;
    } catch (e) {
      element.focus();
      return true;
    }
  }
  return false;
}

// Focus the first focusable child of a container
function focusFirstChild(container) {
  const focusable = container.querySelector(
    'a[href], button, textarea, input, select, [tabindex]:not([tabindex="-1"])'
  );
  if (focusable) {
    focusable.focus();
    return focusable;
  }
  // Fallback: focus the container itself
  container.setAttribute('tabindex', '-1');
  container.focus();
  return container;
}

class RovingTabindex {
  constructor(container) {
    this.container = container;
    this.items = [...container.querySelectorAll('[role="menuitem"]')];
    this.setupItems();
  }

  setupItems() {
    this.items.forEach((item, i) => {
      item.setAttribute('tabindex', i === 0 ? '0' : '-1');
      item.addEventListener('keydown', (e) => this.handleKeydown(e, i));
    });
  }

  handleKeydown(e, index) {
    let newIndex = index;
    switch (e.key) {
      case 'ArrowDown':
      case 'ArrowRight':
        e.preventDefault();
        newIndex = (index + 1) % this.items.length;
        break;
      case 'ArrowUp':
      case 'ArrowLeft':
        e.preventDefault();
        newIndex = (index - 1 + this.items.length) % this.items.length;
        break;
      case 'Home':
        e.preventDefault();
        newIndex = 0;
        break;
      case 'End':
        e.preventDefault();
        newIndex = this.items.length - 1;
        break;
      default:
        return;
    }
    this.moveFocus(index, newIndex);
  }

  moveFocus(oldIndex, newIndex) {
    this.items[oldIndex].setAttribute('tabindex', '-1');
    this.items[newIndex].setAttribute('tabindex', '0');
    this.items[newIndex].focus();
  }
}

// Usage
const menu = new RovingTabindex(document.querySelector('[role="menubar"]'));

// After search results load
function loadSearchResults(query) {
  fetch(`/API/search?q=${encodeURIComponent(query)}`)
    .then(res => res.JSON())
    .then(results => {
      const container = document.getElementById('search-results');
      container.innerHTML = renderResults(results);

      // Focus the first result heading
      const heading = container.querySelector('h3');
      if (heading) {
        heading.setAttribute('tabindex', '-1');
        heading.focus();
      }

      // Announce results to screen readers
      const liveRegion = document.getElementById('search-announce');
      liveRegion.textContent = `${results.length} results found for "${query}".`;
    });
}

// After form submission with errors
function handleFormErrors(errors) {
  const errorSummary = document.getElementById('error-summary');
  errorSummary.innerHTML = `<h2>${errors.length} errors found</h2><ul>${
    errors.map(e => `<li>${e.message}</li>`).join('')
  }</ul>`;

  // Focus the error summary
  errorSummary.setAttribute('tabindex', '-1');
  errorSummary.focus();

  // Focus the first invalid field
  const firstInvalid = document.querySelector('[aria-invalid="true"]');
  if (firstInvalid) firstInvalid.focus();
}

// React Router focus management
import { useEffect } from 'React';
import { useLocation } from 'React-router-Dom';

function useRouteFocus() {
  const { pathname } = useLocation();

  useEffect(() => {
    // Try to find the main heading
    const heading = document.querySelector('main h1, main h2, [role="main"] h1');
    if (heading) {
      heading.setAttribute('tabindex', '-1');
      heading.focus({ preventScroll: true });
    } else {
      // Fallback: focus the main landmark
      const main = document.querySelector('main, [role="main"]');
      if (main) {
        main.setAttribute('tabindex', '-1');
        main.focus({ preventScroll: true });
      }
    }

    // Announce page change to screen readers
    const title = document.title;
    const announcer = document.getElementById('route-announcer');
    if (announcer) {
      announcer.textContent = `Navigated to ${title}`;
    }
  }, [pathname]);
}

<!-- Route announcer — visually hidden, announced by screen readers -->
<div id="route-announcer"
     aria-live="polite"
     aria-atomic="true"
     class="sr-only">
</div>

/* Always show focus for keyboard users */
:focus-visible {
  outline: 3px SOLID #005fcc;
  outline-offset: 2px;
  border-radius: 2px;
}

/* Never show focus ring on mouse click */
:focus:not(:focus-visible) {
  outline: none;
}

/* High contrast mode support */
@media (prefers-contrast: high) {
  :focus-visible {
    outline: 3px SOLID Highlight;
    outline-offset: 3px;
  }
}

/* Custom focus ring for specific components */
.doda-button:focus-visible {
  outline: 3px SOLID #005fcc;
  outline-offset: 2px;
  box-shadow: 0 0 0 4px rgba(0, 95, 204, 0.3);
}

.doda-card:focus-visible {
  outline: 2px SOLID #005fcc;
  outline-offset: -2px;
}

<div role="menubar" aria-label="Scan options">
  <button role="menuitem" tabindex="0"
          onclick="activateScan('quick')">
    Quick Scan
  </button>
  <button role="menuitem" tabindex="-1"
          onclick="activateScan('full')">
    Full Scan
  </button>
  <button role="menuitem" tabindex="-1"
          onclick="activateScan('custom')">
    Custom Scan
  </button>
</div>

<script>
  new RovingTabindex(document.querySelector('[role="menubar"]'));
</script>