---
title: "Rendering custom overlays on PDF.js pages with React portals"
canonical_url: "https://www.nutrient.io/blog/pdfjs-rendering-overlays-react-portals/"
md_url: "https://www.nutrient.io/blog/pdfjs-rendering-overlays-react-portals.md"
last_updated: "2026-06-19T17:55:35.327Z"
description: "Learn how to use React portals to inject custom highlight and annotation layers into PDF.js page elements, with proper z-indexing, viewport tracking, and container lifecycle management."
---

**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](https://www.nutrient.io/sdk/web-overview/) 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:

```tsx

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`:

```tsx

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:

```tsx

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](https://www.nutrient.io/blog/pdfjs-coordinate-systems-pdf-to-screen.md) for the math.

```tsx

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:

```css

/* 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:

```tsx

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:

```tsx

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]);

```

```css.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

#### Why do I need React portals to render overlays on PDF.js pages?

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.

#### Why wait for the <code>textlayerrendered</code> event?

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.

#### What does <code>isConnected</code> do and why does it matter?

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.

#### Why does my overlay break text selection?

Without `pointer-events: none` on the overlay container, your `div`s 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.

#### How do I convert PDF coordinates to screen coordinates?

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.

#### How does Nutrient Web SDK compare for this use case?

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](https://www.nutrient.io/guides/web/about/migration-guides/migrating-from-mozilla-pdfjs.md) 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:

```js

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](https://www.nutrient.io/sdk/web-overview/) or follow the [migration guide](https://www.nutrient.io/guides/web/about/migration-guides/migrating-from-mozilla-pdfjs.md) to switch — [talk to Sales](https://www.nutrient.io/contact-sales/?=sdk) about your requirements._
---

## Related pages

- [The business case for accessibility: Five ways it drives enterprise value](/blog/5-ways-accessibility-drives-enterprise-value.md)
- [Advanced Techniques For React Native Ui Components](/blog/advanced-techniques-for-react-native-ui-components.md)
- [Ai Document Automation Extraction To Action](/blog/ai-document-automation-extraction-to-action.md)
- [Accessibility Untangled Why It Matters Guide](/blog/accessibility-untangled-why-it-matters-guide.md)
- [Auto Tagging And Document Accessibility In Dotnet Sdk](/blog/auto-tagging-and-document-accessibility-in-dotnet-sdk.md)
- [The CEO’s AI playbook: Why decision architecture beats model selection](/blog/ceo-ai-playbook-decision-architecture.md)
- [Best Document Viewers](/blog/best-document-viewers.md)
- [Convert One Drive Files To Pdf In Sharepoint](/blog/convert-one-drive-files-to-pdf-in-sharepoint.md)
- [Complete Guide To Pdfjs](/blog/complete-guide-to-pdfjs.md)
- [Create Pdfs With React](/blog/create-pdfs-with-react.md)
- [The CTO’s AI playbook: Why accountability architecture beats orchestration](/blog/cto-ai-playbook-accountability-architecture.md)
- [Document Ai Vs Ocr](/blog/document-ai-vs-ocr.md)
- [Digital Signatures](/blog/digital-signatures.md)
- [Document Viewer](/blog/document-viewer.md)
- [Emerging threats: Your logging system may be an agentic threat vector](/blog/emerging-threats-your-logging-system.md)
- [or](/blog/how-to-build-a-nextjs-pdf-viewer.md)
- [How To Build A React Powerpoint Viewer](/blog/how-to-build-a-react-powerpoint-viewer.md)
- [or](/blog/how-to-build-a-javascript-pdf-viewer-with-pdfjs.md)
- [How To Convert Html To Pdf Using Html2pdf](/blog/how-to-convert-html-to-pdf-using-html2pdf.md)
- [or](/blog/how-to-build-a-reactjs-pdf-viewer-with-react-pdf.md)
- [How To Build A Reactjs Viewer With Pdfjs](/blog/how-to-build-a-reactjs-viewer-with-pdfjs.md)
- [or](/blog/how-to-convert-html-to-pdf-using-wkhtmltopdf-and-python.md)
- [or](/blog/how-to-convert-html-to-pdf-using-react.md)
- [How To Convert Word To Pdf In Nodejs](/blog/how-to-convert-word-to-pdf-in-nodejs.md)
- [How To Create Pdfs With React To Pdf](/blog/how-to-create-pdfs-with-react-to-pdf.md)
- [How To Embed A Pdf Viewer In Your Website](/blog/how-to-embed-a-pdf-viewer-in-your-website.md)
- [base_url tells WeasyPrint where to resolve relative asset paths](/blog/how-to-generate-pdf-reports-from-html-in-python.md)
- [How To Generate Pdf From Html With Nodejs](/blog/how-to-generate-pdf-from-html-with-nodejs.md)
- [Html In Pdf Format](/blog/html-in-pdf-format.md)
- [Nutrient Vs Conga Composer](/blog/nutrient-vs-conga-composer.md)
- [Linearized Pdf](/blog/linearized-pdf.md)
- [Pdf Page Labels](/blog/pdf-page-labels.md)
- [Open Pdf In Your Web App](/blog/open-pdf-in-your-web-app.md)
- [Online Document Viewer](/blog/online-document-viewer.md)
- [Pdf Sdk Performance Benchmark](/blog/pdf-sdk-performance-benchmark.md)
- [Pdfjs Eventbus Guide](/blog/pdfjs-eventbus-guide.md)
- [Pdf Sdk Compliance Security Checklist](/blog/pdf-sdk-compliance-security-checklist.md)
- [Pdfjs Coordinate Systems Pdf To Screen](/blog/pdfjs-coordinate-systems-pdf-to-screen.md)
- [Pdf Ua Compliance Guide](/blog/pdf-ua-compliance-guide.md)
- [Pdfjs Navigation Zoom Rotation](/blog/pdfjs-navigation-zoom-rotation.md)
- [Pdfjs React Viewer Setup](/blog/pdfjs-react-viewer-setup.md)
- [Pdfjs Limitations Commercial Upgrade](/blog/pdfjs-limitations-commercial-upgrade.md)
- [Process Flows](/blog/process-flows.md)
- [Pdfjs Text Search Pdffindcontroller](/blog/pdfjs-text-search-pdffindcontroller.md)
- [or](/blog/sample-blog-updated.md)
- [Convert an HTML file to PDF.](/blog/top-ten-ways-to-convert-html-to-pdf.md)
- [Wcag2 Accessibility Requirements Documents](/blog/wcag2-accessibility-requirements-documents.md)
- [Vector Pdf](/blog/vector-pdf.md)
- [Web Sdk Is Now Headless](/blog/web-sdk-is-now-headless.md)
- [What Are Annotations](/blog/what-are-annotations.md)
- [What Is A Vpat](/blog/what-is-a-vpat.md)
- [Why Your Ai Agent Hallucinates Pdf Table Data](/blog/why-your-ai-agent-hallucinates-pdf-table-data.md)
- [What Is Pdf Ua](/blog/what-is-pdf-ua.md)
- [Why Pdfium Is A Trusted Platform For Pdf Rendering](/blog/why-pdfium-is-a-trusted-platform-for-pdf-rendering.md)