React Frontend Integration

Series: Elasticsearch 101 | Article: 07

---

Overview

From the React side, Elasticsearch is just another data source behind an HTTP API. The frontend never talks to Elasticsearch directly — it calls the Go backend, which proxies and shapes the response. This keeps credentials off the client, allows response transformation, and lets the backend enforce business rules before returning results.

This article covers:

• The search API contract between the Go backend and React frontend

• A reusable useSearch hook

• Debounced input handling

• Rendering search results with highlighted matches

• A faceted filter sidebar driven by aggregation data

• Autocomplete with search_after-style UX

---

Why You Should Not Hit Elasticsearch Directly from React

It is technically possible to call Elasticsearch from the browser using @elastic/elasticsearch (Node.js) or raw fetch calls. I do not do this and recommend against it:

1. Credentials exposure: Elasticsearch API keys in the browser are visible to anyone who opens DevTools.

2. Query leakage: Your entire query structure, field names, and data shape become public.

3. Missing business logic: Is this user allowed to see unpublished drafts? That check lives in Go, not in a browser.

4. CORS complexity: Configuring Elasticsearch's CORS headers for browser access adds maintenance overhead.

Keep the pattern: React → Go API → Elasticsearch.

---

The API Contract

The Go backend from Article 06 exposes:

GET /api/search?q=<query>&tags=<tag1,tag2>&from=<offset>&size=<limit>

Response shape (TypeScript interface):

interface TagFacet {
  tag: string;
  count: number;
}

interface Article {
  id: string;
  title: string;
  slug: string;
  author_name: string;
  tags: string[];
  published_at: string | null;
  view_count: number;
}

interface SearchResponse {
  total: number;
  articles: Article[];
  tag_facets: TagFacet[];
}

Define these types in a shared src/types/search.ts file.

---

The useSearch Hook

Encapsulate all search state and logic in a single custom hook. The component layer stays clean.

// src/hooks/useSearch.ts
import { useState, useEffect, useCallback, useRef } from 'react';

interface SearchParams {
  query: string;
  tags: string[];
  page: number;
  pageSize: number;
}

interface SearchState {
  results: SearchResponse | null;
  loading: boolean;
  error: string | null;
}

export function useSearch(params: SearchParams): SearchState {
  const [state, setState] = useState<SearchState>({
    results: null,
    loading: false,
    error: null,
  });

  // Abort the previous fetch when params change
  const abortRef = useRef<AbortController | null>(null);

  useEffect(() => {
    const controller = new AbortController();
    abortRef.current = controller;

    setState(prev => ({ ...prev, loading: true, error: null }));

    const url = buildSearchURL(params);

    fetch(url, { signal: controller.signal })
      .then(res => {
        if (!res.ok) throw new Error(`Search failed: ${res.status}`);
        return res.json() as Promise<SearchResponse>;
      })
      .then(data => {
        setState({ results: data, loading: false, error: null });
      })
      .catch(err => {
        if (err.name === 'AbortError') return; // cancelled, safe to ignore
        setState({ results: null, loading: false, error: err.message });
      });

    return () => controller.abort();
  }, [params.query, params.tags.join(','), params.page, params.pageSize]);

  return state;
}

function buildSearchURL(params: SearchParams): string {
  const url = new URL('/api/search', window.location.origin);
  if (params.query) url.searchParams.set('q', params.query);
  if (params.tags.length > 0) url.searchParams.set('tags', params.tags.join(','));
  url.searchParams.set('from', String(params.page * params.pageSize));
  url.searchParams.set('size', String(params.pageSize));
  return url.toString();
}

Key behaviors:

• AbortController cancels in-flight requests when params change — prevents stale responses overwriting newer ones.

• The useEffect dependency array uses .join(',') for the tags array to avoid reference instability.

• Errors are stored in state rather than thrown, keeping the component layer simple.

---

Debounced Search Input

Firing a search on every keystroke is wasteful. Debounce the query so the API call fires 300ms after the user stops typing:

// src/hooks/useDebounce.ts
import { useState, useEffect } from 'react';

export function useDebounce<T>(value: T, delay: number): T {
  const [debounced, setDebounced] = useState<T>(value);

  useEffect(() => {
    const timer = setTimeout(() => setDebounced(value), delay);
    return () => clearTimeout(timer);
  }, [value, delay]);

  return debounced;
}

---

Search Page Component

// src/pages/SearchPage.tsx
import { useState } from 'react';
import { useDebounce } from '../hooks/useDebounce';
import { useSearch } from '../hooks/useSearch';
import { SearchInput } from '../components/SearchInput';
import { SearchResults } from '../components/SearchResults';
import { TagFacetSidebar } from '../components/TagFacetSidebar';
import { Pagination } from '../components/Pagination';

const PAGE_SIZE = 10;

export function SearchPage() {
  const [rawQuery, setRawQuery] = useState('');
  const [selectedTags, setSelectedTags] = useState<string[]>([]);
  const [page, setPage] = useState(0);

  const query = useDebounce(rawQuery, 300);

  const { results, loading, error } = useSearch({
    query,
    tags: selectedTags,
    page,
    pageSize: PAGE_SIZE,
  });

  function toggleTag(tag: string) {
    setSelectedTags(prev =>
      prev.includes(tag) ? prev.filter(t => t !== tag) : [...prev, tag]
    );
    setPage(0); // reset pagination when filter changes
  }

  function handleQueryChange(value: string) {
    setRawQuery(value);
    setPage(0);
  }

  const totalPages = results ? Math.ceil(results.total / PAGE_SIZE) : 0;

  return (
    <div className="search-page">
      <SearchInput value={rawQuery} onChange={handleQueryChange} loading={loading} />

      {error && <p className="error">{error}</p>}

      <div className="search-layout">
        <aside>
          <TagFacetSidebar
            facets={results?.tag_facets ?? []}
            selected={selectedTags}
            onToggle={toggleTag}
          />
        </aside>
        <main>
          <p>{results?.total ?? 0} results</p>
          <SearchResults articles={results?.articles ?? []} />
          {totalPages > 1 && (
            <Pagination page={page} total={totalPages} onChange={setPage} />
          )}
        </main>
      </div>
    </div>
  );
}

---

Search Input Component

// src/components/SearchInput.tsx
interface Props {
  value: string;
  onChange: (value: string) => void;
  loading: boolean;
}

export function SearchInput({ value, onChange, loading }: Props) {
  return (
    <div className="search-input-wrapper">
      <input
        type="search"
        value={value}
        onChange={e => onChange(e.target.value)}
        placeholder="Search articles..."
        aria-label="Search articles"
      />
      {loading && <span className="spinner" aria-label="Loading" />}
    </div>
  );
}

---

Tag Facet Sidebar

// src/components/TagFacetSidebar.tsx
import type { TagFacet } from '../types/search';

interface Props {
  facets: TagFacet[];
  selected: string[];
  onToggle: (tag: string) => void;
}

export function TagFacetSidebar({ facets, selected, onToggle }: Props) {
  if (facets.length === 0) return null;

  return (
    <div className="facet-sidebar">
      <h3>Filter by tag</h3>
      <ul>
        {facets.map(({ tag, count }) => (
          <li key={tag}>
            <label>
              <input
                type="checkbox"
                checked={selected.includes(tag)}
                onChange={() => onToggle(tag)}
              />
              {tag}
              <span className="facet-count">{count}</span>
            </label>
          </li>
        ))}
      </ul>
    </div>
  );
}

---

Rendering Search Results with Highlights

When the Go backend returns highlighted excerpts, render them as HTML. Keep the highlight wrapping tags configurable so styled components can override the default <em>:

// src/components/SearchResults.tsx
import type { Article } from '../types/search';

interface Props {
  articles: Article[];
  highlights?: Record<string, string[]>; // keyed by article id
}

export function SearchResults({ articles, highlights = {} }: Props) {
  if (articles.length === 0) return <p>No results found.</p>;

  return (
    <ul className="results-list">
      {articles.map(article => {
        const bodyExcerpts = highlights[article.id] ?? [];
        return (
          <li key={article.id} className="result-item">
            <a href={`/articles/${article.slug}`}>
              <h2>{article.title}</h2>
            </a>
            <p className="result-meta">
              {article.author_name} &bull; {formatDate(article.published_at)}
            </p>
            {bodyExcerpts.map((excerpt, i) => (
              <p
                key={i}
                className="result-excerpt"
                // The backend sends <em> tags; allow only that tag
                dangerouslySetInnerHTML={{ __html: sanitizeHighlight(excerpt) }}
              />
            ))}
            <div className="result-tags">
              {article.tags.map(tag => (
                <span key={tag} className="tag">{tag}</span>
              ))}
            </div>
          </li>
        );
      })}
    </ul>
  );
}

function formatDate(iso: string | null): string {
  if (!iso) return 'Draft';
  return new Date(iso).toLocaleDateString('en-US', {
    year: 'numeric', month: 'short', day: 'numeric',
  });
}

// Only allow <em> and </em> — strip everything else
function sanitizeHighlight(raw: string): string {
  return raw.replace(/<(?!\/?(em)>)[^>]+>/g, '');
}

The sanitizeHighlight regex allows only <em> and </em>. Never render raw backend-supplied HTML without sanitization, even from your own API.

---

URL State Synchronization

For shareable search URLs, sync the query and filters to the URL:

// src/hooks/useSearchParams.ts
import { useSearchParams } from 'react-router-dom';

export function useSearchState() {
  const [searchParams, setSearchParams] = useSearchParams();

  const query = searchParams.get('q') ?? '';
  const tags = searchParams.getAll('tag');
  const page = Number(searchParams.get('page') ?? '0');

  function updateQuery(q: string) {
    setSearchParams(prev => {
      const next = new URLSearchParams(prev);
      if (q) next.set('q', q); else next.delete('q');
      next.delete('page');
      return next;
    });
  }

  function toggleTag(tag: string) {
    setSearchParams(prev => {
      const next = new URLSearchParams(prev);
      const current = next.getAll('tag');
      next.delete('tag');
      if (current.includes(tag)) {
        current.filter(t => t !== tag).forEach(t => next.append('tag', t));
      } else {
        [...current, tag].forEach(t => next.append('tag', t));
      }
      next.delete('page');
      return next;
    });
  }

  function setPage(p: number) {
    setSearchParams(prev => {
      const next = new URLSearchParams(prev);
      if (p > 0) next.set('page', String(p)); else next.delete('page');
      return next;
    });
  }

  return { query, tags, page, updateQuery, toggleTag, setPage };
}

This gives users shareable URLs like /search?q=elasticsearch&tag=backend&tag=golang.

---

Autocomplete / Typeahead

Add a GET /api/suggest?q=<prefix> endpoint on the Go side using a match_phrase_prefix query or completion field. On the React side, the pattern is:

// src/hooks/useSuggestions.ts
import { useState, useEffect } from 'react';
import { useDebounce } from './useDebounce';

export function useSuggestions(input: string) {
  const [suggestions, setSuggestions] = useState<string[]>([]);
  const debounced = useDebounce(input, 200);

  useEffect(() => {
    if (debounced.length < 2) {
      setSuggestions([]);
      return;
    }

    const controller = new AbortController();

    fetch(`/api/suggest?q=${encodeURIComponent(debounced)}`, {
      signal: controller.signal,
    })
      .then(r => r.json())
      .then(data => setSuggestions(data.suggestions ?? []))
      .catch(err => { if (err.name !== 'AbortError') console.error(err); });

    return () => controller.abort();
  }, [debounced]);

  return suggestions;
}

Minimum 2 characters before triggering suggestions avoids very broad queries and unnecessary load.

---

Summary

• Never call Elasticsearch directly from the browser — always proxy through the Go backend.

• Encapsulate all search logic in a useSearch hook; keep components presentational.

• Debounce the text input (300ms is a reasonable default).

• Use AbortController to cancel in-flight requests on param change.

• Sync search state to URL query parameters for shareable links.

• Sanitize highlight HTML before setting dangerouslySetInnerHTML.

• Drive the facet sidebar from aggregation data returned by the single search request.

---

Previous: Go Backend Integration | Next: Production Best Practices