How To Support Links Without Using the PDFViewer?

[cmcnicholas]

I have an application that wants to quite heavily modify viewing/interaction of the PDF's being viewerd. I've looked through the code examples and they all show the PDFViewer and PDFLinkService, but my question is how would I implement this without the viewer? e.g. I am currently handling document, page navigation, when to call render etc. etc.

I can see PDFLinkService accepts in its constructor:

    eventBus,
    externalLinkTarget = null,
    externalLinkRel = null,
    ignoreDestinationZoom = false,

which should be something I can provide it but just wondered if I'm going about this the wrong way? Do I need to implement my own LinkService?

[christianalberto]

To support links in PDF.js **without using PDFViewer**, you do not necessarily need to rewrite PDFLinkService. Instead, you need to instantiate and render the AnnotationLayer, optionally passing in a lightweight custom link service or a configured PDFLinkService.

In PDF.js, links (both external URLs and internal page jumps) are annotations. They are handled by rendering an HTML AnnotationLayer on top of your <canvas>.

---

Option 1: Render AnnotationLayer with a Minimal Custom linkService

If you are managing your own page rendering and navigation (e.g., custom page change handlers), creating a small object adhering to the IPDFLinkService interface is usually much cleaner than instantiating the full PDFLinkService (which expects references to a pdfViewer object).

import * as pdfjsLib from 'pdfjs-dist';

// 1. Create a minimal linkService interface
const customLinkService = {
  // Return target setting for external links (e.g. 1 = _blank)
  externalLinkTarget: 2, // 2 maps to LinkTarget.BLANK
  externalLinkRel: 'noopener noreferrer',
  
  // Handle internal destination links (e.g., jump to page 3)
  async goToDestination(dest) {
    if (typeof dest === 'string') {
      dest = await pdfDocument.getDestination(dest);
    }
    if (Array.isArray(dest)) {
      const pageRef = dest[0];
      const pageNumber = await pdfDocument.getPageIndex(pageRef) + 1;
      
      // Call your custom navigation handler here!
      myCustomNavigateToPage(pageNumber);
    }
  },

  // Handle named destination actions/page numbers
  navigateTo(dest) {
    this.goToDestination(dest);
  },

  // Get anchor URL string for a destination
  getDestinationHash(dest) {
    return '#';
  },

  // Action execution (e.g., named actions)
  executeNamedAction(action) {
    if (action === 'NextPage') myCustomNavigateToPage(currentPage + 1);
    if (action === 'PrevPage') myCustomNavigateToPage(currentPage - 1);
  }
};

// 2. Render Page and Annotation Layer
async function renderPageWithLinks(pageNumber) {
  const page = await pdfDocument.getPage(pageNumber);
  const viewport = page.getViewport({ scale: 1.5 });

  // Render Canvas
  const canvas = document.getElementById('pdf-canvas');
  const context = canvas.getContext('2d');
  canvas.width = viewport.width;
  canvas.height = viewport.height;

  await page.render({ canvasContext: context, viewport }).promise;

  // Render Annotation Layer for Links
  const annotations = await page.getAnnotations();
  const annotationLayerDiv = document.getElementById('annotation-layer');
  
  // Clear previous page annotations
  annotationLayerDiv.innerHTML = '';
  annotationLayerDiv.style.width = `${viewport.width}px`;
  annotationLayerDiv.style.height = `${viewport.height}px`;

  // Instantiate and render AnnotationLayer
  const annotationLayer = new pdfjsLib.AnnotationLayer({
    div: annotationLayerDiv,
    accessibilityManager: null,
    annotationCanvasMap: null,
    page: page,
    viewport: viewport.clone({ dontFlip: true }),
  });

  await annotationLayer.render({
    annotations,
    renderForms: false,
    linkService: customLinkService,
    downloadManager: null,
    page: page,
    viewport: viewport.clone({ dontFlip: true }),
  });
}

---

Option 2: Using the built-in PDFLinkService

If you want to use the official PDFLinkService from pdfjs-dist/web/pdf_viewer.mjs, you can initialize it without PDFViewer, but you must supply the document and binding handlers:

import { PDFLinkService, EventBus } from 'pdfjs-dist/web/pdf_viewer.mjs';

const eventBus = new EventBus();
const linkService = new PDFLinkService({
  eventBus,
  externalLinkTarget: 2, // Open external links in new tab
  externalLinkRel: 'noopener noreferrer'
});

// Bind document to linkService once loaded
linkService.setDocument(pdfDocument);

// Bind custom viewer surrogate so internal links work correctly
linkService.setViewer({
  scrollPageIntoView({ pageNumber }) {
    // Custom logic to switch page in your app
    myCustomNavigateToPage(pageNumber);
  }
});

---

Required CSS Setup

For the AnnotationLayer link boxes to position correctly over the <canvas>, make sure your CSS container positions them absolute:

.pdf-container {
  position: relative;
}

.annotationLayer {
  position: absolute;
  top: 0;
  left: 0;
  pointer-events: none; /* Let background clicks pass through */
}

/* Enable pointer events on actual clickable link elements */
.annotationLayer .linkAnnotation {
  pointer-events: auto;
}