You build search into your PDF viewer.

A user searches for a phrase. The viewer finds the correct match. The result count looks right, and clicking a result takes the user to the correct page.

But the highlight appears a few pixels away from the text.

Then the user zooms in. The highlight moves.

Rotate the page, and the problem gets worse.

It looks like a small UI bug. In reality, it often points to a deeper issue: the search engine and the rendering interface are not using the same coordinate system.

A PDF viewer does not have just one representation of a page
When you build a viewer with PDF.js, you need to distinguish between the document's content and the way that content is displayed.

The rendering layer draws the page. The text layer makes text selectable and supports interactions such as searching. Annotations add another layer of interactive content.

These layers serve different purposes, but they must remain geometrically consistent.

A search engine might know that a phrase appears at a particular position in the extracted text. The interface, however, needs a rectangle representing where that phrase appears on the rendered page.

Those are two different pieces of information.

Finding a string is not the same as locating it on the screen.

  1. Build a reliable connection between text and geometry

Suppose the document contains:

  • Payment must be completed within 30 days.
  • The user searches for 30 days.

Your search logic identifies the matching characters. To highlight the match, you also need the geometry corresponding to those characters.

That means maintaining a relationship between the extracted text and the positions of the individual text items or character ranges.

This becomes more complicated when the document contains:

  • Multiple text items separated by spaces.
  • Words split across separate text objects.
  • Different fonts and font sizes.
  • Line breaks and rotated text.
  • Mixed writing directions.
  • Ligatures and unusual character mappings.

A naive implementation that searches each text item independently may miss matches spanning multiple items.

Another implementation might concatenate all the text successfully but lose the positional information needed to highlight the match.

A robust search implementation needs to preserve both.

2. Do not confuse PDF coordinates with screen coordinates

PDF pages have their own coordinate systems. Browser rendering introduces viewport dimensions, scale, rotation, and positioning.

If your match bounds are calculated in one coordinate system and drawn in another, the result will drift.

For every page, the rendering and highlighting logic must agree on the relevant transformations.

A practical debugging sequence is:

  • Search for a short phrase on a simple, unrotated page.
  • Record the extracted text and its bounds.
  • Draw a debug rectangle around the expected match.
  • Change the zoom level and compare the result.
  • Repeat with a rotated page.
  • Test a phrase spanning multiple text items.

If the rectangle is correct before zooming but wrong afterward, investigate the viewport transformation.

If it is wrong at every scale, investigate text-to-geometry mapping first.

This distinction can save hours of trial-and-error CSS changes.

3. Make search and highlighting share the same geometry logic

One architectural mistake is implementing search highlighting separately from other features that need to locate text.

Imagine that document search calculates a match's position using one function, while annotation creation uses another. Each function handles text spacing, scaling, and rotation slightly differently.

The search result may look correct while a highlight annotation lands elsewhere.

The better approach is to centralise the coordinate calculations wherever possible.

For example, shared utilities can handle:

  • Mapping text ranges to page bounds.
  • Converting page coordinates into viewport coordinates.
  • Applying scale and rotation transformations.
  • Normalising rectangles before drawing them.

The exact implementation depends on the rendering library and the features your viewer supports. The important principle is to avoid multiple independent definitions of where a piece of text is located.

4. Test the cases that ordinary PDFs hide

A viewer that works on a simple invoice may still fail on complex documents.

Build a small test collection containing:

  • A paragraph with several text items on one line.

  • A search phrase that spans a line break.

  • Rotated text. Pages with different dimensions.

Documents containing repeated occurrences of the same phrase.

Text with unusual fonts or character spacing.

Test selection, search highlighting, navigation, and annotation placement against the same documents.

Also distinguish between text that is genuinely extractable and text that exists only as pixels in a scanned page. A text-search implementation cannot reliably find image-only text without OCR or another recognition step.

Building these interactions into a React viewer

Search, text selection, and annotations can look like separate features in a product demo. Underneath, they often depend on the same difficult problem: maintaining the relationship between document content and its geometry.

We have been working on TeamSync PDF Viewer, an open-source PDF viewer SDK for React applications with client-side rendering, document search, annotations, and other PDF interactions.

Explore the code here:

https://github.com/angelbot-ai/TeamSync-PDF-Viewer

You can inspect the implementation, try the viewer in your own environment, and see whether its approach fits your project.

A question for PDF.js developers

Have you encountered a case where search returned the correct text but the highlight was misplaced?

Was the problem caused by text extraction, coordinate transformations, rotation, or something else entirely?

I'd be interested in hearing about the edge cases you've had to handle.

If you find the repository useful, consider giving it a star, trying it in a project, or sharing a reproducible issue or improvement.

Practical feedback from developers working with real documents is always valuable.