Skip to content
Tutorials Center
My learning

Topics

Lesson 38 of 39 ยท Projects and Practice

Project: A Live Search with Debounce and Suspense

Build a live search in SolidJS with a debounced input, createResource, Suspense, an ErrorBoundary, keyboard navigation and highlighted matches, step by step.

A search box that shows results as you type is a perfect project for the async tools of this track. It needs debouncing, a resource tied to a signal, Suspense for loading, an ErrorBoundary for failures, and some careful UI for empty results and keyboard use.

The "API" here is a function that filters a built-in list of programming topics after a short delay, and fails on purpose when you type boom. That keeps every run deterministic and works inside the sandbox. In a real app only searchApi changes: it would call fetch and throw if res.ok is false.

Requirements

  1. Typing updates a debounced query; no request for an empty query.
  2. Results load through a resource; the old results stay visible while the next ones load (no flash).
  3. Matching text is highlighted, safely.
  4. Empty and error states have clear messages and a retry.
  5. Arrow keys move through results and Enter picks one.
flowchart LR
  I["input (text)"] --> D["debounced(text)"]
  D --> R["createResource(query, searchApi)"]
  R --> V["results list + states"]
  K["keyboard: active index"] --> V

Input feeds a debounced signal; the debounced value is the resource source; the list reads the resource.

Step 1: the highlight helper

Highlighting is the one place where beginners create security bugs. Never build HTML strings from user text and inject them as HTML. Split the text into segments and render them as text and elements:

Step 1: safe highlighting

Because we only ever create text nodes and <mark> elements from these segments, the second example (a hostile string) is displayed literally instead of executing.

Step 2: the whole app

Step 2: the live search

Experiment: type s (many results, highlighted), keep typing si (the old list stays while the new one loads), type zzz (empty state), type boom (error with a retry button), and use the arrow keys and Enter. In this stand-in the ErrorBoundary catches the rejection because reading results.latest in an errored resource rethrows it.

How the pieces cooperate

  • Debounce: query follows text with a 300 ms delay, so typing "signals" quickly makes one request.
  • Source signal: props.query || null pauses the resource for an empty string, so there is no request and no "Searching..." flicker.
  • results.latest: shows the previous list while the next one loads, instead of the blank state you would get from results() inside Suspense.
  • ErrorBoundary: the failure is contained to the results area; the input keeps working.
  • Active index: a signal reset whenever new results arrive, so the highlight never points past the end of the list.

Going further

  1. Add aria-activedescendant and ids to the options for screen readers.
  2. Cache searches in a Map so going back to an earlier query is instant.
  3. Replace the stand-in with a real fetch and an AbortController aborted in onCleanup (async patterns).
  4. In SolidStart, move the search into a query with createAsync and keep the text in the URL with useSearchParams, so results are shareable (route data).
  5. Write tests: a fake API, findByText for results, and a test for the error state (testing).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why use results.latest for the list instead of results()?

    Reading latest never suspends or throws on loading, so the list does not flash away.
  2. 2. Why does the highlighter return segments instead of an HTML string?

    Building HTML from user text invites cross-site scripting. Text nodes are always safe.
  3. 3. What does a source of null do for the resource?

    A falsy source means 'not ready', so the fetcher does not run.
  4. 4. Where does the error from a rejected search get handled?

    Reading an errored resource rethrows, and the nearest ErrorBoundary renders its fallback.

Summary

  • Compose a debounced signal, a resource and a boundary into a robust live search.
  • Skip requests for empty input with a falsy source; show latest to avoid flashing.
  • Highlight with segments, never with injected HTML.
  • Contain errors in an ErrorBoundary with a retry; keep keyboard state in a signal that resets with the data.

Next: Practice: SolidJS Challenges