Migrating from Apryse WebViewer to Syncfusion React PDF Viewer

26 Mar 20269 minutes to read

This guide assists developers in migrating applications built with Apryse WebViewer to the Syncfusion React PDF Viewer. It focuses on architectural differences, feature mapping, and required changes in a React environment.

Overview

Apryse WebViewer is a feature-rich PDF SDK that relies on a modular JavaScript API.

Syncfusion React PDF Viewer provides a native React component-based PDF viewing experience with built-in UI, annotations, forms, and performance optimizations, using an optimized JavaScript rendering engine and without external runtime dependencies.

Architecture notes

This guide focuses on replacing an Apryse WebViewer integration with a Syncfusion React PDF Viewer component. Key considerations when migrating include the integration pattern (imperative SDK mounts vs. a declarative React component), how UI/tooling is provided (hosted JS modules vs. injected services), and enable feature and persistence for annotations and form fields. The instructions below are framed to help migrate code, event handlers, and persistence workflows to the PdfViewerComponent.

Installation

Apryse WebViewer

npm install @pdftron/webviewer

Syncfusion React PDF Viewer

npm install @syncfusion/ej2-react-pdfviewer

Viewer Initialization Comparison

Apryse WebViewer

import { useRef, useEffect } from 'react';
import WebViewer from '@pdftron/webviewer';

import './App.css';

function App() {
  const viewer = useRef(null);

  useEffect(() => {
    WebViewer(
      {
        path: 'lib/webviewer',
        licenseKey: 'YOUR_LICENSE_KEY',
        initialDoc: 'https://pdftron.s3.amazonaws.com/downloads/pl/demo-annotated.pdf',
      },
      viewer.current
    ).then((instance) => {
      // You can access the WebViewer instance here if needed
    });
  }, []);

  return (
    <div className="webviewer" ref={viewer}></div>
  );
}

export default App;

Syncfusion React PDF Viewer

Standalone

import * as ReactDOM from 'react-dom/client';
import * as React from 'react';
import './index.css';
import { PdfViewerComponent, Toolbar, Magnification, Navigation, LinkAnnotation, BookmarkView,
         ThumbnailView, Print, TextSelection, Annotation, TextSearch, FormFields, FormDesigner, Inject} from '@syncfusion/ej2-react-pdfviewer';

function App() {
    return (<div>
    <div className='control-section'>
    {/* Render the PDF Viewer */}
      <PdfViewerComponent
        id="container"
        documentPath="https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf"
        resourceUrl="https://cdn.syncfusion.com/ej2/31.2.2/dist/ej2-pdfviewer-lib"
        style={{ 'height': '640px' }}>

         <Inject services={[ Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, BookmarkView,
                             ThumbnailView, Print, TextSelection, TextSearch, FormFields, FormDesigner ]}/>

      </PdfViewerComponent>
    </div>
  </div>);
}
const root = ReactDOM.createRoot(document.getElementById('sample'));
root.render(<App />);

Feature checklist (Syncfusion)

• Page Navigation
• Text Search
• Annotations
• Form Fields

Event Handling

Apryse

Check Events Guide to know more about event handling in Apryse.

documentViewer.addEventListener('documentLoaded', () => {
  console.log('Document loaded');
});

Syncfusion

Check Syncfusion Events Guide to know more about event handling in Syncfusion React PDF Viewer.

<PdfViewerComponent
  documentLoad={() => console.log('Document loaded')}
/>

Migration Checklist

• Remove WebViewer initialization and DOM-based mounting
• Replace Apryse APIs with PdfViewerComponent configuration
• Map annotation and form workflows to built-in services
• Re-validate licensing and feature availability

Tutorial: quick migration recipe

Follow these concise steps to replace an Apryse WebViewer integration with PdfViewerComponent.

1) Prepare the project

• Keep a working branch and add simple checks for current behavior (open document, navigate pages, annotation toggle).
• Install Syncfusion React PDF Viewer:

npm install @syncfusion/ej2-react-pdfviewer

2) Add required CSS and resources

Add the Syncfusion CSS imports to your global stylesheet (e.g., src/index.css) and decide whether to use the CDN resourceUrl or host ej2-pdfviewer-lib locally in public/.

@import '../node_modules/@syncfusion/ej2-base/styles/material.css';
@import '../node_modules/@syncfusion/ej2-buttons/styles/material.css';
@import '../node_modules/@syncfusion/ej2-inputs/styles/material.css';
@import '../node_modules/@syncfusion/ej2-navigations/styles/material.css';
@import '../node_modules/@syncfusion/ej2-popups/styles/material.css';
@import '../node_modules/@syncfusion/ej2-pdfviewer/styles/material.css';

To host local resources, copy:

cp -R ./node_modules/@syncfusion/ej2-pdfviewer/dist/ej2-pdfviewer-lib public/ej2-pdfviewer-lib

3) Replace initialization

• Apryse mounts a WebViewer instance into a DOM element; replace that mount with a React PdfViewerComponent. Move configuration options into PdfViewerComponent props and inject only required services.

4) Migrate features incrementally

• Start with basic viewing (document load, page navigation), then add search, annotations, and forms.
• For each feature, map the Apryse API usage to the Syncfusion method/event (see API mapping below), update back-end persistence for annotations if needed, and run the smoke checks.

Minimal file difference (before → after)

This small, copy-paste difference shows a single-file replacement pattern: remove the WebViewer DOM mount and replace with a React component that uses PdfViewerComponent.

Before (e.g., src/viewers/OldWebViewer.js):

import WebViewer from '@pdftron/webviewer';

WebViewer({
  path: '/lib',
  initialDoc: 'sample.pdf'
}, document.getElementById('viewer'))
.then(instance => {
  const { documentViewer, annotationManager } = instance.Core;
  // existing custom wiring
});

After (e.g., src/components/PdfViewer.jsx):

Standalone

import React from 'react';
import { PdfViewerComponent, Toolbar, Inject } from '@syncfusion/ej2-react-pdfviewer';

export default function PdfViewer() {
  return (
    <PdfViewerComponent
      id="pdfViewer"
      documentPath="/assets/sample.pdf"
      resourceUrl="/assets/ej2-pdfviewer-lib"
      style={{ height: '700px' }}
    >
      <Inject services={[Toolbar]} />
    </PdfViewerComponent>
  );
}

API mapping: Apryse WebViewer → Syncfusion equivalents

Apryse WebViewer	Syncfusion React PDF Viewer
WebViewer({ path, initialDoc }, element)	Use <PdfViewerComponent documentPath="..." resourceUrl="..." /> and load() for programmatic loads.
instance.Core.documentViewer (page events)	pageRenderInitiate, pageRenderComplete, pageChange, documentLoad events.
annotationManager (add/serialize annotations)	addAnnotation(), importAnnotation(), exportAnnotation(), exportAnnotationsAsBase64String() methods and annotationAdd event.
documentViewer.getAnnotationManager()	Use PdfViewerComponent methods for annotations and annotation events.
Custom UI modules	Use the Toolbar service or ToolbarComponent for custom toolbar items and handle toolbarClick.
Text search APIs	Enable enableTextSearch or call extractText() for programmatic text extraction.
Form field APIs	Use formField* events: formFieldClick, validateFormFields, retrieveFormFields, exportFormFieldsAsObject.
Print / Export modules	download() and Print service.

Expanded Migration Checklist (concrete actions)

• Create a migration branch and add simple smoke tests for: document load, page navigation, text search, add annotation, and download.
• Remove @pdftron/webviewer initialization and related DOM-manipulation code.
• Install and import @syncfusion/ej2-react-pdfviewer and required CSS.
• Replace the DOM mount with a React component: create PdfViewer.jsx / PdfViewer.tsx and update app routes.
• Add resourceUrl configuration or copy ej2-pdfviewer-lib into public/ for local hosting.
• Inject only necessary services (e.g., Toolbar, Annotation, FormFields, TextSearch) to limit bundle size.
• Migrate event handlers:
  • Apryse documentLoaded → Syncfusion documentLoad.
  • Apryse page render callbacks → pageRenderComplete and pageRenderInitiate.
  • Apryse annotation events → Syncfusion annotationAdd, annotationRemove, etc.
• Migrate annotation persistence: adapt serialization format or use Syncfusion export/import helpers.
• Migrate form workflows to Syncfusion formField events and verify validation hooks.
• Replace any WebViewer-specific custom UI with Syncfusion toolbar/custom toolbar items and toolbarClick handling.
• Test thoroughly on supported browsers and performance with large PDFs.
• Remove obsolete tests and code paths tied to Apryse.

Reference: key Syncfusion PdfViewerComponent methods & events

• PdfViewerComponent API index
• load() — programmatically load a PDF.
• download() — trigger download of current document.
• addAnnotation(annotation: any) — add an annotation programmatically.
• exportAnnotation(annotationDataFormat) / exportAnnotationsAsBase64String(): — export annotations for persistence.
• extractText(pageIndex: number, options?: any): — extract text and coordinates.
• Events: documentLoad, pageRenderComplete, pageChange, annotationAdd, annotationRemove, toolbarClick.

See Also

• Apryse WebViewer Getting Started
• Syncfusion React PDF Viewer Getting Started