Rendering custom overlays on PDF.js pages with React portals

PDF.js renders each page inside its own DOM element. This guide shows how to use React portals to inject custom overlay layers — like highlights and annotations — into PDF.js page elements so they scroll, zoom, and rotate with each page.

TL;DR

PDF.js owns the DOM tree for each rendered page. To overlay highlights or annotations that scroll, zoom, and rotate with the page, inject a container div into each .page element and render React into it via createPortal. The pattern has four moving parts:

Find or create an overlay container inside each .page div.
Wait for the textlayerrendered event before creating containers.
Recheck container.isConnected after every page rerender (zoom invalidates the DOM).
Recompute positions on scalechanging and rotationchanging using pageView.viewport.

If you’d rather not maintain this glue, Nutrient Web SDK exposes a customRenderers API that handles the lifecycle for you.

PDF.js renders each page inside its own DOM element. To add highlights, annotations, or other visual overlays, you need to inject custom layers into these page elements. React portals are the perfect tool for this.

The problem

PDF.js controls its own DOM tree:

#pdf-container
  .pdfViewer
    .page[data-page-number="1"]
      .canvasWrapper
        canvas
      .textLayer
    .page[data-page-number="2"]
      ...

You can’t just render React components next to the canvas — they need to live inside each .page element to scroll, zoom, and rotate with the page.

Step 1: Find or create a layer container

For each page, create a <div> inside the .page element to host your overlay:

function findOrCreateContainerLayer(container, className) {
  let layer = container.querySelector(`.${className}`);
  if (!layer) {
    layer = document.createElement("div");
    layer.className = className;
    container.append(layer);
  }
  return layer;
}
function findOrCreateHighlightLayer(viewer, pageNumber) {
  const pageView = viewer.getPageView(pageNumber - 1);
  if (!pageView?.div) return null;
  return findOrCreateContainerLayer(
    pageView.div,
    "custom-highlight-layer",
  );
}

This gives you:

.page[data-page-number="1"]
  .canvasWrapper
  .textLayer
  .custom-highlight-layer    <-- your overlay container

Step 2: Wait for text layer rendering

You can only create overlay containers after the page’s text layer has rendered. Listen for textlayerrendered:

import React from "react";
// Group an array of items by their `.page` property.
function groupByPage(items) {
  return items.reduce((acc, item) => {
    (acc[item.page] ||= []).push(item);
    return acc;
  }, {});
}
function useOverlayPortals(viewer, eventBus, pdfDocument, data) {
  const containers = React.useRef({});
  const [portals, setPortals] = React.useState([]);
  const dataByPage = React.useMemo(() => groupByPage(data), [data]);
  React.useEffect(() => {
    const renderOverlays = () => {
      const portalList = [];
      for (let page = 1; page <= pdfDocument.numPages; page++) {
        // Reuse existing container if still connected to DOM.
        let container = containers.current[page];
        if (!container?.isConnected) {
          container = findOrCreateHighlightLayer(viewer, page);
          if (container) containers.current[page] = container;
        }
        if (container) {
          portalList.push({
            element: container,
            data: dataByPage[page] || [],
            page,
          });
        }
      }
      setPortals(portalList);
    };
    renderOverlays();
    eventBus.on("textlayerrendered", renderOverlays);
    return () => {
      eventBus.off("textlayerrendered", renderOverlays);
    };
  }, [viewer, eventBus, pdfDocument, dataByPage]);
  return portals;
}

Step 3: Render via React portals

Wire useOverlayPortals into a component that renders each portal. The component calls createPortal with the container from step 1 and the page data grouped in step 2:

import { useContext } from "react";
import { createPortal } from "react-dom";
import { PDFContext } from "./PDFContext";
function HighlightOverlay({ locations, onClear }) {
  const { viewer, eventBus, pdfDocument } = useContext(PDFContext);
  const portals = useOverlayPortals(
    viewer.current,
    eventBus.current,
    pdfDocument.current,
    locations,
  );
  return (
    <>
      {portals.map(({ element, data, page }, index) =>
        createPortal(
          <HighlightLayer
            page={page}
            locations={data}
            onClear={onClear}
          />,
          element,
          `highlight-${index}`,
        ),
      )}
    </>
  );
}

Step 4: Position elements using viewport

Inside each portal, convert PDF coordinates to CSS positions. pdfToScreen and nodeLocationToScaled below are your own coordinate-conversion helpers — see PDF.js coordinate systems for the math.

function HighlightLayer({ page, locations, onClear }) {
  const { viewer, eventBus } = useContext(PDFContext);
  const [viewport, setViewport] = React.useState(undefined);
  // Update viewport on scale/rotation changes.
  React.useEffect(() => {
    const update = () => {
      const pageView = viewer.current?.getPageView(page - 1);
      if (pageView?.viewport) setViewport(pageView.viewport);
    };
    update();
    eventBus.current?.on("scalechanging", update);
    eventBus.current?.on("rotationchanging", update);
    return () => {
      eventBus.current?.off("scalechanging", update);
      eventBus.current?.off("rotationchanging", update);
    };
  }, [page, viewer, eventBus]);
  if (!viewport) return null;
  return locations.map((location, i) => {
    const position = pdfToScreen(
      nodeLocationToScaled(location),
      viewport,
    );
    return (
      <div
        key={i}
        onDoubleClick={onClear}
        style={{
          position: "absolute",
          background: "rgba(96, 4, 255, 0.2)",
          left: position.left,
          top: position.top,
          width: position.width,
          height: position.height,
        }}
      />
    );
  });
}

CSS layer ordering

The overlay layer needs a proper z-index to sit above the canvas but allow text selection through it:

/* Ensure highlight layer appears above canvas but below text. */
.custom-highlight-layer {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  pointer-events: none; /* Allow text selection through. */
  z-index: 1;
}
.custom-highlight-layer > div {
  pointer-events: auto; /* But highlights themselves are clickable. */
}
/* Override PDF.js text layer z-index if needed. */
.textLayer {
  z-index: 2 !important;
}

Checking container connectivity

PDF.js may rerender pages (e.g. on zoom), destroying your injected containers. Always check isConnected before reusing:

const container = containers.current[page];
if (container?.isConnected) {
  // Reuse — still in the DOM.
} else {
  // Recreate — page was rerendered.
  containers.current[page] = findOrCreateHighlightLayer(viewer, page);
}

Toggling visibility and interactivity

Use CSS classes to show/hide overlays or disable interaction when annotation tools are active:

React.useEffect(() => {
  for (const portal of portals) {
    // Hide when annotations are toggled off.
    portal.element.classList.toggle("hidden", !showAnnotations);
    // Disable pointer events when drawing new annotations.
    portal.element.classList.toggle("noInteraction", isDrawing);
  }
}, [portals, showAnnotations, isDrawing]);

.hidden { display: none; }
.noInteraction { pointer-events: none !important; }

Key takeaways

Use createPortal() to render React components inside PDF.js page divs.
Wait for textlayerrendered before creating overlay containers.
Check isConnected to handle page rerenders.
Recompute coordinates on scalechanging and rotationchanging.
Use pointer-events: none on the container, auto on individual items.
Store container refs in a useRef map keyed by page number.

FAQ

PDF.js controls the DOM tree for each page. Rendering React siblings next to the canvas means your overlay won’t scroll, zoom, or rotate with the page. createPortal lets you render React components into a DOM node that lives inside each .page element, so the page’s own transforms apply automatically.

PDF.js renders pages asynchronously: The canvas paints first, followed by the text layer and then the annotation layer. The .page element exists earlier, but appending a sibling to it before the text layer is ready can race with PDF.js’s own DOM mutations and result in your container being wiped. textlayerrendered fires when the page is fully laid out and safe to extend.

PDF.js may rerender a page when zoom or rotation changes — and rerendering replaces the old .page DOM subtree entirely, orphaning any nodes you injected. Node.isConnected returns false for nodes that have been detached. Checking it before reusing a container catches the rerender and forces you to create a fresh layer.

Without pointer-events: none on the overlay container, your divs intercept mouse events that would otherwise reach the text layer. Set pointer-events: none on the container and pointer-events: auto only on the individual overlay items that need to be clickable. Combined with a z-index lower than the text layer (z-index: 1 on overlay, z-index: 2 on .textLayer), selection and interaction both work.

Use the viewport object that PDF.js attaches to each page view: viewer.getPageView(pageIndex).viewport. The viewport provides convertToViewportPoint(x, y) for points and convertToViewportRectangle([x1, y1, x2, y2]) for rectangles, plus a transform matrix you can compose with your own coordinates. Recompute on scalechanging and rotationchanging events.

Nutrient’s customRenderers API lets you provide your own DOM or React element for any annotation type. The SDK handles positioning, z-index, scaling, rotation, and lifecycle — no portals, no textlayerrendered listeners, no isConnected checks. See the migration guide for information on moving from PDF.js.

How Nutrient Web SDK handles this

With Nutrient, there are no React portals, no DOM injection, no textlayerrendered event listeners, and no isConnected checks to manage. Nutrient’s custom renderer API lets you provide your own UI for any annotation type while the SDK handles positioning, scaling, and lifecycle:

const instance = await NutrientViewer.load({
  container: "#pdf-container",
  document: "document.pdf",
  customRenderers: {
    Annotation: ({ annotation }) => {
      // Return a custom React/DOM element for any annotation.
      const node = document.createElement("div");
      node.className = "custom-overlay";
      node.textContent = annotation.text?.value || "";
      return { node, append: true };
    },
  },
});

The SDK also includes 17+ built-in annotation types with automatic z-index management and zoom-aware rendering.

For a managed alternative, see Nutrient Web SDK or follow the migration guide to switch — talk to Sales about your requirements.

推荐订阅源

Inside Nutrient

Table of contents