Search-as-you-type: implementation plan

TL;DR

Today the search box fires one request per keystroke and shows whichever response lands last. This plan adds a 250 ms debounce and cancels the superseded request with AbortController, so results always match what is in the box.

• In scope: the header search box, the useSearch hook, the fetch client, tests, a feature flag.
• Out of scope: server-side ranking, search history, keyboard navigation of results.
• Done means: typing "react hooks" never shows results for "react ho", and the Network tab shows aborted requests rather than parallel ones.

What the user sees

Four states of the search box. The key rule: old results stay on screen while a new request is loading, so the list never flashes empty.

IDLE (fewer than 2 characters)
+-----------------------------+
| (search) Search products... |
+-----------------------------+
 Type 2 or more characters

LOADING (old results stay visible)
+-----------------------------+
| (search) react ho      (...)|
+-----------------------------+
 React Hooks Handbook   (dim)
 React Hooks in Depth   (dim)

RESULTS
+-----------------------------+
| (search) react hooks     (x)|
+-----------------------------+
 React Hooks Handbook
 React Hooks in Depth
 Hooks Cheat Sheet        3 hits

EMPTY and ERROR
+-----------------------------+
| (search) zzzq            (x)|
+-----------------------------+
 No results for "zzzq"

 Error: Search failed (503)
 [ Retry ]

How the data flows

Everything between the keystroke and the screen runs in the browser except one request. The hook useSearch is the only place that owns an AbortController.

What happens when two queries overlap

The case this feature exists for: the user keeps typing while request A is still in flight.

Decisions worth a look

Debounce delay

Requests fired while typing "react hooks" in a recorded burst-typing session.

Other choices

Code to review

1. The debounce hook

Debounce the value, not the handler. The cleanup clears the timer on every change, which is the whole trick.

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

export function useDebouncedValue<T>(value: T, delayMs = 250): T {
  const [debounced, setDebounced] = useState(value);

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

  return debounced;
}

2. The search hook with cancellation

The cleanup function aborts the previous request. The AbortError guard stops a cancelled request from being reported as a failure.

// src/hooks/useSearch.ts
const MIN_CHARS = 2;

export function useSearch(query: string): SearchState {
  const [state, setState] = useState<SearchState>({ status: 'idle', items: [] });

  useEffect(() => {
    const q = query.trim();
    if (q.length < MIN_CHARS) {
      setState({ status: 'idle', items: [] });
      return undefined;
    }

    const controller = new AbortController();
    setState((s) => ({ ...s, status: 'loading' })); // keep old items on screen

    searchApi(q, controller.signal)
      .then((items) =>
        setState({ status: items.length ? 'ok' : 'empty', items }),
      )
      .catch((err) => {
        if (err.name === 'AbortError') return; // superseded, not a failure
        setState({ status: 'error', items: [], error: err.message });
      });

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

  return state;
}

3. The fetch client

// src/api/search.ts
export async function searchApi(q: string, signal: AbortSignal): Promise<Item[]> {
  const res = await fetch(`/api/search?q=${encodeURIComponent(q)}`, { signal });
  if (!res.ok) throw new Error(`Search failed (${res.status})`);
  return (await res.json()).items;
}

4. The component

// src/components/SearchBox.tsx
export function SearchBox() {
  const [text, setText] = useState('');
  const debounced = useDebouncedValue(text, 250);
  const { status, items, error } = useSearch(debounced);

  return (
    <div role="search">
      <input
        value={text}
        onChange={(e) => setText(e.target.value)}
        aria-busy={status === 'loading'}
        aria-controls="search-results"
      />
      <ResultsList id="search-results" status={status} items={items} error={error} />
    </div>
  );
}

5. The test that proves cancellation

// src/hooks/useSearch.test.ts
it('aborts the previous request when the query changes', async () => {
  const signals: AbortSignal[] = [];
  vi.spyOn(api, 'searchApi').mockImplementation((_q, signal) => {
    signals.push(signal);
    return new Promise(() => {}); // never resolves
  });

  const { rerender } = renderHook(({ q }) => useSearch(q), {
    initialProps: { q: 're' },
  });
  rerender({ q: 'rea' });

  expect(signals).toHaveLength(2);
  expect(signals[0].aborted).toBe(true);
  expect(signals[1].aborted).toBe(false);
});

State machine

Files

Risks and edge cases

Test plan

Schedule

Rollout

1. 1
   Merge behind the searchDebounce flag2026-10-26
   Priya
2. 2
   Enable for internal staff2026-10-28
   Priya
3. 3
   Enable for 10% of traffic and watch request volume2026-10-29
   Marcus
4. 4
   Full rollout, remove the flag next sprint2026-10-30
   Marcus

Open questions

• Does /api/search cancel work when the client disconnects?
• Should the 60 s cache survive route changes, or reset on navigation?
• Is 2 characters the right minimum for non-Latin scripts?

Back to the examples