Accessible Combobox / Autocomplete Pattern

<!-- Combobox container -->
<div class="combobox">
  <label for="country-input">Choose a country</label>

  <input
    type="text"
    id="country-input"
    role="combobox"
    aria-expanded="false"
    aria-autocomplete="list"
    aria-controls="country-listbox"
    aria-activedescendant=""
    autocomplete="off"
  >

  <ul role="listbox" id="country-listbox" hidden>
    <li role="option" id="opt-1" aria-selected="false">
      Australia
    </li>
    <li role="option" id="opt-2" aria-selected="false">
      Brazil
    </li>
    <li role="option" id="opt-3" aria-selected="false">
      Canada
    </li>
    <!-- More options... -->
  </ul>

  <!-- Live region for result count -->
  <div class="sr-only" aria-live="polite"
       id="combo-status"></div>
</div>

.combobox {
  position: relative;
  max-width: 20rem;
}

.combobox label {
  display: block;
  font-weight: 600;
  margin-bottom: 0.25rem;
}

.combobox input[role="combobox"] {
  width: 100%;
  padding: 0.5rem 1rem;
  font-size: 0.875rem;
  border: 2px solid #d1d5db;
  border-radius: 0.25rem;
  background: #fff;
  /* SC 2.5.8: minimum 24x24 target */
  min-height: 2.75rem;
  box-sizing: border-box;
}

/* SC 2.4.13: focus indicator with 3:1 contrast */
.combobox input[role="combobox"]:focus-visible {
  outline: 2px solid #5b2a86;
  outline-offset: 2px;
  border-color: #5b2a86;
}

.combobox [role="listbox"] {
  position: absolute;
  top: 100%;
  left: 0;
  right: 0;
  margin: 0;
  padding: 0.25rem 0;
  list-style: none;
  background: #fff;
  border: 2px solid #d1d5db;
  border-radius: 0.25rem;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  max-height: 14rem;
  overflow-y: auto;
  z-index: 10;
}

.combobox [role="listbox"][hidden] {
  display: none;
}

.combobox [role="option"] {
  padding: 0.5rem 1rem;
  cursor: pointer;
  /* SC 2.5.8: minimum 24x24 target */
  min-height: 2.75rem;
  display: flex;
  align-items: center;
}

.combobox [role="option"]:hover {
  background: #f3f4f6;
}

/* Active option via aria-selected */
.combobox [role="option"][aria-selected="true"] {
  background: #5b2a86;
  color: #fff;
}

/* Respect reduced motion */
@media (prefers-reduced-motion: reduce) {
  .combobox input,
  .combobox [role="listbox"] {
    transition: none;
  }
}

/* Screen reader only — live region */
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

function initCombobox(container) {
  const input = container.querySelector('[role="combobox"]');
  const listbox = container.querySelector('[role="listbox"]');
  const status = container.querySelector('[aria-live]');
  const allOptions = Array.from(
    listbox.querySelectorAll('[role="option"]')
  );
  let activeIndex = -1;

  function getVisibleOptions() {
    return allOptions.filter(
      opt => !opt.hidden
    );
  }

  function openListbox() {
    listbox.hidden = false;
    input.setAttribute('aria-expanded', 'true');
  }

  function closeListbox() {
    listbox.hidden = true;
    input.setAttribute('aria-expanded', 'false');
    input.setAttribute('aria-activedescendant', '');
    clearSelection();
    activeIndex = -1;
  }

  function clearSelection() {
    allOptions.forEach(opt => {
      opt.setAttribute('aria-selected', 'false');
    });
  }

  function setActiveOption(index) {
    const visible = getVisibleOptions();
    if (visible.length === 0) return;

    clearSelection();
    activeIndex = index;
    const option = visible[activeIndex];
    option.setAttribute('aria-selected', 'true');
    input.setAttribute(
      'aria-activedescendant', option.id
    );

    // Scroll option into view if needed
    option.scrollIntoView({ block: 'nearest' });
  }

  function selectOption(option) {
    input.value = option.textContent.trim();
    closeListbox();
  }

  function filterOptions() {
    const query = input.value.toLowerCase().trim();
    let matchCount = 0;

    allOptions.forEach(opt => {
      const text = opt.textContent.toLowerCase();
      const matches = text.includes(query);
      opt.hidden = !matches;
      if (matches) matchCount++;
    });

    activeIndex = -1;
    clearSelection();
    input.setAttribute('aria-activedescendant', '');

    if (query.length > 0 && matchCount > 0) {
      openListbox();
      // Announce count via live region
      status.textContent =
        matchCount + (matchCount === 1
          ? ' result available'
          : ' results available');
    } else if (query.length > 0) {
      openListbox();
      status.textContent = 'No results available';
    } else {
      closeListbox();
      status.textContent = '';
    }
  }

  // Filter on input
  input.addEventListener('input', filterOptions);

  // Keyboard navigation
  input.addEventListener('keydown', (e) => {
    const visible = getVisibleOptions();

    switch (e.key) {
      case 'ArrowDown':
        e.preventDefault();
        if (listbox.hidden) {
          filterOptions();
          openListbox();
        }
        if (visible.length > 0) {
          const next = activeIndex < visible.length - 1
            ? activeIndex + 1 : 0;
          setActiveOption(next);
        }
        break;

      case 'ArrowUp':
        e.preventDefault();
        if (visible.length > 0) {
          const prev = activeIndex > 0
            ? activeIndex - 1
            : visible.length - 1;
          setActiveOption(prev);
        }
        break;

      case 'Home':
        if (listbox.hidden) return;
        e.preventDefault();
        if (visible.length > 0) {
          setActiveOption(0);
        }
        break;

      case 'End':
        if (listbox.hidden) return;
        e.preventDefault();
        if (visible.length > 0) {
          setActiveOption(visible.length - 1);
        }
        break;

      case 'Enter':
        e.preventDefault();
        if (activeIndex >= 0) {
          selectOption(visible[activeIndex]);
        }
        break;

      case 'Escape':
        if (!listbox.hidden) {
          e.preventDefault();
          closeListbox();
        }
        break;

      case 'Tab':
        if (activeIndex >= 0 && !listbox.hidden) {
          selectOption(visible[activeIndex]);
        } else {
          closeListbox();
        }
        // Don't prevent default — let Tab
        // move focus to the next field
        break;
    }
  });

  // Click to select an option
  listbox.addEventListener('click', (e) => {
    const option = e.target.closest('[role="option"]');
    if (option && !option.hidden) {
      selectOption(option);
      input.focus();
    }
  });

  // Close on outside click
  document.addEventListener('click', (e) => {
    if (!container.contains(e.target)) {
      closeListbox();
    }
  });
}

// Initialize all comboboxes on the page
document.querySelectorAll('.combobox')
  .forEach(initCombobox);