Search

Search has three parts: Search extracts the document's text, useSearch finds matches, and HighlightLayer draws a selected result. Mount Search once per viewer. Keep Pages outside it so indexing does not replace the document with a loading message.

A searchable viewer

This example searches on submit to avoid doing fuzzy matching on every keystroke. It uses the pdf-setup.ts from installation.

"use client";
 
import {
  CanvasLayer, HighlightLayer, Page, Pages, Root, Search, TextLayer,
  calculateHighlightRects, usePdf, usePdfJump, useSearch,
  type SearchResult,
} from "@anaralabs/lector";
import { useState } from "react";
import "./pdf-setup";
 
function SearchPanel() {
  const [query, setQuery] = useState("");
  const [submitted, setSubmitted] = useState(false);
  const [error, setError] = useState<string | null>(null);
  const { search, searchResults } = useSearch();
  const getPage = usePdf((state) => state.getPdfPageProxy);
  const { jumpToHighlightRects } = usePdfJump();
  const setHighlight = usePdf((state) => state.setHighlight);
  const results = [...searchResults.exactMatches, ...searchResults.fuzzyMatches];
 
  async function openResult(result: SearchResult) {
    setError(null);
    try {
      const rects = await calculateHighlightRects(getPage(result.pageNumber), result);
      jumpToHighlightRects(rects, "pixels", "center");
    } catch {
      setError("Couldn't locate this match on the page.");
    }
  }
 
  return (
    <div>
      <form onSubmit={(event) => {
        event.preventDefault();
        search(query, { limit: 20 });
        setHighlight([]);
        setSubmitted(true);
        setError(null);
      }}>
        <label>
          Find in document
          <input value={query} onChange={(event) => setQuery(event.target.value)} />
        </label>
        <button type="submit">Search</button>
      </form>
      <p role="status">
        {submitted ? `${results.length} results shown` : "Enter text to search."}
      </p>
      {error && <p role="alert">{error}</p>}
      <ul>
        {results.map((result) => (
          <li key={`${result.pageNumber}-${result.matchIndex}-${result.isExactMatch}`}>
            <button type="button" onClick={() => void openResult(result)}>
              Page {result.pageNumber}: {result.text}
              {!result.isExactMatch && " (similar match)"}
            </button>
          </li>
        ))}
      </ul>
    </div>
  );
}
 
export default function SearchableViewer() {
  return (
    <Root source="/sample.pdf" style={{ height: 600, display: "flex", flexDirection: "column" }}>
      <div style={{ maxHeight: 200, overflow: "auto" }}>
        <Search loading={<p role="status">Indexing document…</p>}>
          <SearchPanel />
        </Search>
      </div>
      <div style={{ flex: 1, minHeight: 0 }}>
        <Pages>
          <Page>
            <CanvasLayer />
            <TextLayer />
            <HighlightLayer style={{ background: "#ffdf6080" }} />
          </Page>
        </Pages>
      </div>
    </Root>
  );
}

calculateHighlightRects uses the result's page number, match index, and matched length (falling back to searchText) to locate the match. Passing the result itself keeps highlighting tied to the submitted query even if the user has since edited the input. It returns pixel rectangles in page coordinates.

Search options and results

search(text, options) is synchronous. It returns the results and also updates searchResults in that hook instance.

Results contain exactMatches, fuzzyMatches, and hasMoreResults. Each match has pageNumber, text, matchIndex, score, isExactMatch, and optional searchText and matchLength. Offsets and lengths refer to the original PDF text in UTF-16 code units. matchLength is present when the matched span differs from searchText.length, for example when case conversion expands a Unicode character. Pass the whole result to calculateHighlightRects to retain the correct span. Matching is case-insensitive. Searching an empty or whitespace-only query clears results.

When both groups have enough matches, exact matches receive ceil(limit / 2) slots and fuzzy matches receive the remainder. Unused slots are filled from the other group. hasMoreResults indicates that candidates exceed the shared budget. For “show more,” rerun the submitted query with a higher limit; results are not paginated.

Equivalent text and wrapped lines

Both search methods normalize canonical Unicode equivalents (café and cafe\u0301), Latin presentation ligatures (fi and fi), soft hyphens, and whitespace. These count as exact matches, including with threshold: 1. The original text is preserved for snippets and highlight offsets; mathematical compatibility symbols such as ² and ① are not converted to ordinary digits.

Search retains PDF.js hasEOL boundaries separately from the concatenated text. A phrase such as first second can therefore match two adjacent lines without incorrectly matching firstsecond. Chinese and Japanese line wraps between Han/kana characters add no space. Extraction order still comes from PDF.js; this is not a column or table reconstruction algorithm.

const { searchAsync } = useSearch();
 
// In a search action: match accented spellings and words split across lines.
const results = await searchAsync(query, {
  threshold: 1,
  matchDiacritics: false,
  ignoreHyphenation: true,
});

Hard-hyphen joining is opt-in because a line-ending hyphen may belong to a compound word. It does not join across an explicit blank line or across pages. A soft hyphen is discretionary formatting and is always ignored. Normalization uses Intl.Segmenter when a Unicode conversion changes a grapheme; include a polyfill if your browser targets do not provide it.

For custom indexes, the exported PageText type has { pageNumber, text, lineBreaks? }. lineBreaks is an immutable sorted array of UTF-16 offsets immediately after items whose hasEOL is true. Keep text as the original concatenated strings and replace the array when boundaries change. Do not insert separators into that string if you will use PDF.js highlight geometry. matchIndex and matchLength continue to address those original strings.

Practical limits

Search extracts text from all pages, even though Pages only renders a viewport's worth of pages. Mount the search panel on demand for large PDFs. For search-as-you-type, debounce the query and measure with representative documents; lowering the result limit does not stop the full-document matching pass.

Image-only scans need an OCR text layer before they can be searched. PDF text extraction can also differ from visual reading order or spacing. Check the extracted text when a phrase looks present but is not found.

Live example

Responsive search in long documents

useSearch() also exposes searchAsync, cancelSearch, and isSearching. searchAsync returns the same ranked results as search, but yields between batches so the browser can process input. It defaults to an approximate 8 ms work budget. Scheduling can increase total search time; the benefit is responsiveness.

const { searchAsync, cancelSearch, searchResults, isSearching } = useSearch();
const [searchError, setSearchError] = useState<Error | null>(null);
 
useEffect(() => {
  setSearchError(null);
  void searchAsync(debouncedSearchText, { limit: 10 }).catch((error) => {
    if (error.name !== "AbortError") setSearchError(error);
  });
  return cancelSearch;
}, [debouncedSearchText, searchAsync, cancelSearch]);

A newer call to either search method cancels pending async work from that hook. Unmounting or replacing document text also cancels it. Cancelled calls reject with AbortError and never publish partial results. You can pass an external AbortSignal through { signal } or adjust { timeSliceMs } when needed. Keep the component inside <Root> and use <Search> to index the document.

Indexing failures and retry

If text extraction fails, Search keeps its children unmounted and shows an error with a Retry button. Retry starts a new indexing attempt without reloading the viewer. To match your application's error presentation, provide a fallback:

<Search
  errorFallback={({ retry }) => (
    <p role="alert">
      Search is unavailable. <button onClick={retry}>Try again</button>
    </p>
  )}
>
  <SearchPanel />
</Search>

This fragment replaces the existing Search wrapper in the example above. The fallback also receives the original error. It handles indexing failures; Root.onError handles document loading failures.