Bug: Popups vanish after scrolling fast

[straeter]

The popups ("HighlightPopup") that show the comment on a grey background vanish when scrolling the pdf pages very fast.

It can be reproduced already with the default example -> use the scroll-handle on the right to scroll quickly up and down and then the popups of the highlights on the first page will not show anymore. I tested this on Chrome and Firefox.

I noticed this behaviour in a forked version with a higher number of highlights + more information per highlight so I guess the problem gets worse with more payload.

I assume it has to do with the way / order how the highlights (and popups) are rendered when the pdf page is loaded.

I will look into this further - unless someone understands what is going on?

[kashaf12]

@straeter

You're absolutely right: the highlight popups disappear when you scroll quickly, especially when there are a lot of them. Let me explain why this happens and what i did to fix it.

💡 What was going wrong?

This issue comes from how PDF.js handles performance. To keep things fast, PDF.js removes the DOM elements for pages that are far off-screen and recreates them when they come back into view.

That’s smart — but our React-based highlight system didn’t know this was happening. It kept trying to render into DOM elements that were already destroyed by PDF.js. Imagine trying to hang a picture on a wall that no longer exists — that’s basically what our code was doing.

So when you scrolled quickly, the popup system got out of sync with PDF.js, and the highlights stopped showing up.

✅ How we fixed it

We updated the highlight rendering logic to play nicely with PDF.js’s lifecycle. Here's what changed:

1. Wait for the right time to render
   We now listen to events like pagerendered and textlayerrendered, so we know exactly when a page is ready before trying to render highlights on it.

2. Check that the DOM is still valid
   Before reusing an old React root, we check if its container still exists in the current DOM. If not, we clean it up and create a new one.

3. Clean up when scrolling away
   When pages go out of view (during fast scrolls), we proactively clean up their React roots. This keeps memory usage low and avoids trying to reuse broken DOM elements.

4. Always start fresh if needed
   If a page’s DOM was recreated by PDF.js, we make sure to clear the old content and start with a brand-new React root.

🚀 Why it works now

By syncing up our React component logic with PDF.js's rendering behavior, everything stays in the right place. We no longer assume the DOM is stable — instead, we react (pun intended 😄) to changes in the page lifecycle.

So even during fast scrolling, highlights now reappear as expected because our rendering code always checks that it’s rendering into a valid, up-to-date container.

---

🔧 Minimal code fix

Here’s the core of the fix, broken down into the 3 most important steps:

// 1. Listen to PDF.js page render events
eventBus.on("pagerendered", this.onPageRendered);

// 2. Re-render highlights when a page is done rendering
onPageRendered = (event) => {
  const pageNumber = event.pageNumber;
  setTimeout(() => {
    this.renderHighlightLayerForPage(pageNumber);
  }, 0);
};

// 3. Make sure the DOM is valid before rendering
private renderHighlightLayerForPage(pageNumber: number) {
  const layer = this.findOrCreateHighlightLayer(pageNumber);
  if (!layer) return;

  const existingRoot = this.highlightReactRoots[pageNumber];

  if (existingRoot) {
    const rootContainer = layer.querySelector('[data-reactroot], [data-react-root]') || layer;

    if (!rootContainer || !document.contains(rootContainer)) {
      existingRoot.unmount?.();
      delete this.highlightReactRoots[pageNumber];
    }
  }

  if (!this.highlightReactRoots[pageNumber]) {
    layer.innerHTML = '';
    const newRoot = createRoot(layer);
    this.highlightReactRoots[pageNumber] = newRoot;
  }

  this.renderHighlightLayer(this.highlightReactRoots[pageNumber], pageNumber);
}

Let me know if anything’s unclear or if you want help adapting this to your forked version!