Building a Search Bar with JS Debouncing Guide

<div class="search-container" role="combobox" aria-expanded="false" aria-haspopup="listbox">
  <label for="search-input" class="sr-only">Search articles</label>
  <div class="search-input-wrapper">
    <svg class="search-icon" aria-hidden="true" viewBox="0 0 24 24" width="20" height="20">
      <circle cx="11" cy="11" r="8" stroke="currentColor" stroke-width="2" fill="none"/>
      <line x1="21" y1="21" x2="16.65" y2="16.65" stroke="currentColor" stroke-width="2"/>
    </svg>
    <input
      id="search-input"
      type="search"
      placeholder="Search articles..."
      autocomplete="off"
      aria-autocomplete="list"
      aria-controls="search-results"
    >
    <button id="clear-btn" class="clear-btn" aria-label="Clear search" hidden>X</button>
  </div>
 
  <div id="search-results" class="search-results" role="listbox" hidden>
    <!-- Results injected by JavaScript -->
  </div>
 
  <div id="search-status" class="search-status" aria-live="polite"></div>
</div>

.search-container {
  position: relative;
  max-width: 600px;
  margin: 0 auto;
}
 
.search-input-wrapper {
  display: flex;
  align-items: center;
  border: 2px solid #e2e8f0;
  border-radius: 8px;
  padding: 8px 12px;
  background: var(--bg-primary, #fff);
  transition: border-color 0.2s;
}
 
.search-input-wrapper:focus-within {
  border-color: #3b82f6;
  box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.15);
}
 
#search-input {
  flex: 1;
  border: none;
  outline: none;
  font-size: 1rem;
  background: transparent;
  color: var(--text-primary, #1e293b);
  margin-left: 8px;
}
 
.search-icon { color: #94a3b8; }
 
.clear-btn {
  background: none;
  border: none;
  cursor: pointer;
  color: #94a3b8;
  font-size: 1rem;
  padding: 4px;
}
 
.search-results {
  position: absolute;
  top: 100%;
  left: 0;
  right: 0;
  margin-top: 4px;
  background: var(--bg-primary, #fff);
  border: 1px solid #e2e8f0;
  border-radius: 8px;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
  max-height: 400px;
  overflow-y: auto;
  z-index: 100;
}
 
.result-item {
  padding: 12px 16px;
  cursor: pointer;
  border-bottom: 1px solid #f1f5f9;
}
 
.result-item:hover,
.result-item.active {
  background: #f1f5f9;
}
 
.result-item mark {
  background: #fef08a;
  color: inherit;
  padding: 0 2px;
  border-radius: 2px;
}
 
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
}

function debounce(fn, delay) {
  let timeoutId;
 
  function debounced(...args) {
    clearTimeout(timeoutId);
    timeoutId = setTimeout(() => fn.apply(this, args), delay);
  }
 
  debounced.cancel = () => {
    clearTimeout(timeoutId);
    timeoutId = null;
  };
 
  return debounced;
}

class SearchClient {
  constructor(baseUrl) {
    this.baseUrl = baseUrl;
    this.controller = null;
  }
 
  async search(query) {
    // Cancel any in-flight request
    if (this.controller) {
      this.controller.abort();
    }
    this.controller = new AbortController();
 
    const url = `${this.baseUrl}?q=${encodeURIComponent(query)}&limit=10`;
 
    const response = await fetch(url, {
      signal: this.controller.signal,
    });
 
    if (!response.ok) {
      throw new Error(`Search failed: ${response.status}`);
    }
 
    return response.json();
  }
 
  cancel() {
    if (this.controller) {
      this.controller.abort();
      this.controller = null;
    }
  }
}

function highlightMatch(text, query) {
  if (!query.trim()) return text;
 
  // Escape regex special characters in the query
  const escaped = query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
  const regex = new RegExp(`(${escaped})`, "gi");
 
  return text.replace(regex, "<mark>$1</mark>");
}

function renderResults(results, query, container) {
  if (results.length === 0) {
    container.innerHTML = `
      <div class="no-results" role="option">
        <p>No results found for "${escapeHtml(query)}"</p>
      </div>
    `;
    return;
  }
 
  container.innerHTML = results
    .map(
      (result, index) => `
      <div class="result-item" role="option" id="result-${index}" data-url="${result.url}">
        <div class="result-title">${highlightMatch(escapeHtml(result.title), query)}</div>
        <div class="result-excerpt">${highlightMatch(escapeHtml(result.excerpt), query)}</div>
        <span class="result-category">${escapeHtml(result.category)}</span>
      </div>
    `
    )
    .join("");
}
 
function escapeHtml(str) {
  const div = document.createElement("div");
  div.textContent = str;
  return div.innerHTML;
}

class KeyboardNavigator {
  constructor(container, onSelect) {
    this.container = container;
    this.onSelect = onSelect;
    this.activeIndex = -1;
  }
 
  handleKey(event) {
    const items = this.container.querySelectorAll(".result-item");
    if (items.length === 0) return;
 
    switch (event.key) {
      case "ArrowDown":
        event.preventDefault();
        this.activeIndex = Math.min(this.activeIndex + 1, items.length - 1);
        this.updateActive(items);
        break;
 
      case "ArrowUp":
        event.preventDefault();
        this.activeIndex = Math.max(this.activeIndex - 1, -1);
        this.updateActive(items);
        break;
 
      case "Enter":
        if (this.activeIndex >= 0 && items[this.activeIndex]) {
          event.preventDefault();
          this.onSelect(items[this.activeIndex]);
        }
        break;
 
      case "Escape":
        this.reset();
        break;
    }
  }
 
  updateActive(items) {
    items.forEach((item) => item.classList.remove("active"));
 
    if (this.activeIndex >= 0 && items[this.activeIndex]) {
      items[this.activeIndex].classList.add("active");
      items[this.activeIndex].scrollIntoView({ block: "nearest" });
    }
  }
 
  reset() {
    this.activeIndex = -1;
    this.container.querySelectorAll(".result-item").forEach((item) => {
      item.classList.remove("active");
    });
  }
}

class SearchBar {
  constructor(options) {
    this.input = document.getElementById("search-input");
    this.results = document.getElementById("search-results");
    this.status = document.getElementById("search-status");
    this.clearBtn = document.getElementById("clear-btn");
    this.container = this.input.closest(".search-container");
 
    this.client = new SearchClient(options.apiUrl);
    this.navigator = new KeyboardNavigator(this.results, (item) => {
      window.location.href = item.dataset.url;
    });
 
    this.minQueryLength = options.minQueryLength || 2;
    this.debouncedSearch = debounce(this.performSearch.bind(this), 300);
 
    this.bindEvents();
  }
 
  bindEvents() {
    this.input.addEventListener("input", (e) => {
      const query = e.target.value.trim();
      this.clearBtn.hidden = query.length === 0;
 
      if (query.length < this.minQueryLength) {
        this.hideResults();
        return;
      }
 
      this.debouncedSearch(query);
    });
 
    this.input.addEventListener("keydown", (e) => {
      this.navigator.handleKey(e);
      if (e.key === "Escape") this.hideResults();
    });
 
    this.clearBtn.addEventListener("click", () => {
      this.input.value = "";
      this.clearBtn.hidden = true;
      this.hideResults();
      this.client.cancel();
      this.input.focus();
    });
 
    this.results.addEventListener("click", (e) => {
      const item = e.target.closest(".result-item");
      if (item) window.location.href = item.dataset.url;
    });
 
    document.addEventListener("click", (e) => {
      if (!this.container.contains(e.target)) {
        this.hideResults();
      }
    });
  }
 
  async performSearch(query) {
    this.showLoading();
 
    try {
      const data = await this.client.search(query);
      renderResults(data.results, query, this.results);
      this.showResults();
 
      this.status.textContent = `${data.results.length} result${data.results.length === 1 ? "" : "s"} found`;
      this.navigator.reset();
    } catch (error) {
      if (error.name === "AbortError") return; // Canceled, ignore
      this.results.innerHTML = '<div class="no-results"><p>Search failed. Try again.</p></div>';
      this.showResults();
    }
  }
 
  showLoading() {
    this.results.innerHTML = '<div class="loading-indicator"><p>Searching...</p></div>';
    this.showResults();
  }
 
  showResults() {
    this.results.hidden = false;
    this.container.setAttribute("aria-expanded", "true");
  }
 
  hideResults() {
    this.results.hidden = true;
    this.container.setAttribute("aria-expanded", "false");
    this.navigator.reset();
    this.status.textContent = "";
    this.debouncedSearch.cancel();
  }
}
 
// Initialize
const search = new SearchBar({ apiUrl: "/api/search" });