Rendering PDFs in Angular and React Applications

Displaying PDF files in a web browser is a common requirement for dashboards, document management systems, and reporting tools. The ecosystem offers several options ranging from low-level rendering engines to high-level UI components. This analysis compares pdfjs-dist, react-pdf, and three Angular-specific wrappers (ng2-pdf-viewer, ng2-pdfjs-viewer, ngx-extended-pdf-viewer) to help you make the right architectural choice.

🏗️ Core Architecture: Engine vs. Wrapper

Understanding the relationship between these packages is critical. pdfjs-dist is the core engine. The others are wrappers that make it easier to use within specific frameworks.

pdfjs-dist is the official Mozilla library. It handles the heavy lifting of parsing and rendering. You manage the DOM and state yourself.

// pdfjs-dist: Manual rendering setup
import * as pdfjsLib from 'pdfjs-dist';

const loadingTask = pdfjsLib.getDocument('file.pdf');
loadingTask.promise.then(function(pdf) {
  pdf.getPage(1).then(function(page) {
    const scale = 1.5;
    const viewport = page.getViewport({ scale: scale });
    const canvas = document.getElementById('the-canvas');
    const context = canvas.getContext('2d');
    canvas.height = viewport.height;
    canvas.width = viewport.width;
    page.render({ canvasContext: context, viewport: viewport });
  });
});

react-pdf wraps this engine in React components. It handles the lifecycle for you.

// react-pdf: Component-based usage
import { Document, Page } from 'react-pdf';

function MyApp() {
  return (
    <Document file="file.pdf">
      <Page pageNumber={1} />
    </Document>
  );
}

ngx-extended-pdf-viewer wraps the engine for Angular with a full UI toolbar.

<!-- ngx-extended-pdf-viewer: Full UI component -->
<ngx-extended-pdf-viewer
  [src]="'file.pdf'"
  [useBrowserLocale]="true"
  height="90vh">
</ngx-extended-pdf-viewer>

ng2-pdf-viewer is an older Angular wrapper that renders pages as canvas elements without the full toolbar UI by default.

<!-- ng2-pdf-viewer: Basic canvas rendering -->
<pdf-viewer
  [src]="pdfSrc"
  [render-text]="true"
  [show-all]="true"
  style="display: block;">
</pdf-viewer>

ng2-pdfjs-viewer is another Angular wrapper that aims to expose more of the underlying PDF.js viewer functionality than the basic canvas renderer.

<!-- ng2-pdfjs-viewer: Exposing viewer options -->
<pdfjs-viewer
  [src]="pdfSrc"
  [show-toolbar]="true"
  style="width: 100%; height: 100%;">
</pdfjs-viewer>

🎨 User Interface: Built-in vs. Custom

The biggest difference lies in how much UI work you want to do yourself.

ngx-extended-pdf-viewer provides a complete interface. It includes zoom controls, page navigation, search, and printing buttons out of the box. This saves weeks of development time if you need a standard reader experience.

<!-- ngx-extended-pdf-viewer: Built-in search and print -->
<ngx-extended-pdf-viewer
  [src]="documentUrl"
  [show-search-button]="true"
  [show-print-button]="true">
</ngx-extended-pdf-viewer>

react-pdf gives you the rendering but not the controls. You must build your own toolbar for zooming or page turning. This offers maximum design flexibility but requires more code.

// react-pdf: Custom controls required
function Reader({ file }) {
  const [numPages, setNumPages] = useState(null);
  const [pageNumber, setPageNumber] = useState(1);

  function onDocumentLoadSuccess({ numPages }) {
    setNumPages(numPages);
  }

  return (
    <div>
      <button onClick={() => setPageNumber(prev => prev - 1)}>Prev</button>
      <Document file={file} onLoadSuccess={onDocumentLoadSuccess}>
        <Page pageNumber={pageNumber} />
      </Document>
      <button onClick={() => setPageNumber(prev => prev + 1)}>Next</button>
    </div>
  );
}

pdfjs-dist requires you to build everything. There is no UI. You are responsible for the canvas, the buttons, and the state management.

// pdfjs-dist: Completely custom UI implementation
const canvas = document.createElement('canvas');
// ... rendering logic ...
document.getElementById('controls').appendChild(canvas);
// You must write event listeners for zoom/pan manually

ng2-pdf-viewer focuses on rendering pages in the flow. It does not include the Adobe-style toolbar by default. You build the navigation logic in your Angular component.

<!-- ng2-pdf-viewer: Custom navigation logic -->
<pdf-viewer
  [src]="src"
  [(page)]="page"
  [zoom]="zoom">
</pdf-viewer>
<button (click)="page = page - 1">Previous</button>
<button (click)="page = page + 1">Next</button>

ng2-pdfjs-viewer attempts to bridge the gap by including some viewer options, but it often requires more configuration to match the polish of ngx-extended-pdf-viewer.

<!-- ng2-pdfjs-viewer: Configuring viewer options -->
<pdfjs-viewer
  [src]="src"
  [options]="{ showToolbar: true }">
</pdfjs-viewer>

⚙️ Configuration and Setup

Setting up the worker file is a common pain point with PDF.js based libraries. The worker is a separate script that handles parsing to keep the UI thread free.

react-pdf requires you to set the worker source explicitly to match the version you are using. Mismatched versions cause runtime errors.

// react-pdf: Setting the worker source
import { pdfjs } from 'react-pdf';

pdfjs.GlobalWorkerOptions.workerSrc = `//cdnjs.cloudflare.com/ajax/libs/pdf.js/${pdfjs.version}/pdf.worker.min.js`;

pdfjs-dist requires similar manual configuration of the GlobalWorkerOptions.

// pdfjs-dist: Manual worker configuration
pdfjsLib.GlobalWorkerOptions.workerSrc = 'path/to/pdf.worker.js';

ngx-extended-pdf-viewer simplifies this for Angular. It often handles the worker path automatically or provides clear Angular CLI configuration steps to copy the assets.

// ngx-extended-pdf-viewer: Angular module config
import { NgxExtendedPdfViewerModule } from 'ngx-extended-pdf-viewer';

@NgModule({
  imports: [
    NgxExtendedPdfViewerModule.useDefaults()
  ]
})
export class AppModule {}

ng2-pdf-viewer requires you to configure the worker source in your root component or module setup, similar to the raw library.

// ng2-pdf-viewer: Worker setup in component
import { PdfViewerModule } from 'ng2-pdf-viewer';
import * as pdfjsLib from 'pdfjs-dist';

pdfjsLib.GlobalWorkerOptions.workerSrc = 'path/to/pdf.worker.js';

ng2-pdfjs-viewer also relies on the underlying pdfjs-dist worker configuration, meaning you must ensure the paths are correct in your build process.

// ng2-pdfjs-viewer: Ensuring worker path is valid
// Typically configured in angular.json assets or component init

📱 Responsiveness and Performance

Performance depends on how the library handles large documents and viewport changes.

react-pdf renders pages as canvas elements. It supports lazy loading pages, which is crucial for large files. You control when pages render.

// react-pdf: Lazy loading pages
<Document file={largeFile}>
  <Page pageNumber={1} renderAnnotationLayer={false} />
  <Page pageNumber={2} renderAnnotationLayer={false} />
</Document>

ngx-extended-pdf-viewer uses the standard PDF.js viewer which includes virtualization (only rendering visible pages). This handles large files well without extra code from you.

<!-- ngx-extended-pdf-viewer: Automatic virtualization -->
<ngx-extended-pdf-viewer
  [src]="largeFile"
  [show-all]="false">
</ngx-extended-pdf-viewer>

pdfjs-dist gives you raw control. You must implement virtualization logic yourself if you want to support 100+ page documents without freezing the browser.

// pdfjs-dist: Manual virtualization logic required
// Listen to scroll events and render only visible pages
container.addEventListener('scroll', () => {
  // Calculate visible range and render pages
});

ng2-pdf-viewer renders all pages by default if show-all is true, which can cause performance issues with large files. You should paginate manually for better performance.

<!-- ng2-pdf-viewer: Pagination for performance -->
<pdf-viewer
  [src]="src"
  [show-all]="false"
  [page]="currentPage">
</pdf-viewer>

ng2-pdfjs-viewer inherits the performance characteristics of the PDF.js viewer it wraps, generally handling virtualization better than basic canvas wrappers.

<!-- ng2-pdfjs-viewer: Viewer mode performance -->
<pdfjs-viewer
  [src]="src"
  [view]="'fit-width'">
</pdfjs-viewer>

⚠️ Maintenance and Deprecation Status

This is a critical factor for long-term projects.

ng2-pdf-viewer is effectively in maintenance mode or deprecated for new features. The community has largely moved to ngx-extended-pdf-viewer. Using this for a new project introduces technical debt.

// ng2-pdf-viewer: Legacy implementation
// Avoid for new projects
import { PdfViewerModule } from 'ng2-pdf-viewer';

ngx-extended-pdf-viewer is actively maintained. It tracks updates to the underlying PDF.js library and fixes Angular-specific integration issues regularly.

// ngx-extended-pdf-viewer: Active maintenance
import { NgxExtendedPdfViewerModule } from 'ngx-extended-pdf-viewer';

react-pdf is the standard for React. It is actively maintained and updated to support recent React versions and PDF.js updates.

// react-pdf: Standard React implementation
import { Document } from 'react-pdf';

pdfjs-dist is maintained by Mozilla. It is stable but changes occasionally in breaking ways, which is why wrappers exist.

// pdfjs-dist: Core engine
import * as pdfjsLib from 'pdfjs-dist';

ng2-pdfjs-viewer has lower adoption and update frequency compared to ngx-extended-pdf-viewer. Verify the latest commit history before relying on it for critical features.

<!-- ng2-pdfjs-viewer: Check maintenance status -->
<pdfjs-viewer [src]="src"></pdfjs-viewer>

📊 Summary: Key Differences

💡 Final Recommendation

For React Developers: Use react-pdf. It is the community standard. You will find the most support and examples online. Be prepared to build your own toolbar.

For Angular Developers: Use ngx-extended-pdf-viewer. It saves significant development time by providing a complete UI. Avoid ng2-pdf-viewer for new work as it is older technology.

For Custom Needs: Use pdfjs-dist only if you are building your own framework wrapper or have very specific rendering requirements that the existing wrappers cannot satisfy.