Syncfusion React Pdf Viewer

Syncfusion React Pdfviewer – UI Sample Generator

Target package: @syncfusion/ej2-react-pdfviewer

Generate Code for the User's Project (default)

Trigger keywords: "how to", "add pdfviewer", "code sample", "show me", "example", "snippet", "integrate", "component", "create sample", "react sample".

Purpose: Generate minimal, copy-pasteable TS and HTML code that the user can integrate directly into their React project.

Workflow: ⚠️ CRITICAL — Feature Support Policy (STRICT MODE):

FUNDAMENTAL RULE: Only generate code using APIs and properties that are EXPLICITLY listed in the reference files. ANY deviation is a VIOLATION.

• MANDATORY CHECKS BEFORE GENERATING ANY CODE:

1. Search the reference files for the exact API/property name 2. Verify it appears in the Method Reference, Properties, or Events tables 3. If NOT found in ANY reference file, STOP immediately 4. Do NOT generate or suggest undocumented APIs under any circumstances

• STRICT ENFORCEMENT - ZERO TOLERANCE:
• NO custom properties - Only use properties from reference file tables
• NO invented methods - Only use methods from reference file tables
• NO workarounds with undefined APIs - Forbidden
• NO assumptions about undocumented behavior - Forbidden
• NO alternative implementations using guess-work - Forbidden
• NO pretending support exists - Forbidden

• MANDATORY RESPONSE FOR UNSUPPORTED FEATURES:
• If a requested scenario/feature/API is NOT listed in any reference file, you MUST respond with:

    "This feature is not supported in the current Syncfusion React PDF Viewer implementation."

• Then list what IS supported from the appropriate reference file
• Never suggest alternatives unless explicitly documented in reference files

• REFERENCE FILE HIERARCHY:
• Each reference file contains complete, authoritative documentation for its domain
• The tables (Method Reference, Properties, Events) are the SOURCE OF TRUTH
• Content outside these tables in reference files is explanatory only
• Do NOT extend beyond what appears in the reference file tables

• AUDIT YOUR GENERATION:
• Before providing any code, verify EVERY API used appears in a reference file table
• Document which reference file each API comes from
• If you cannot cite a reference file table entry, DELETE that code

• This is a CRITICAL REQUIREMENT. Violations compromise the skill's integrity and reliability.

Step 1 — Detect the Application Type (REQUIRED - DO NOT SKIP)

• Use file_search and read_file tools to inspect workspace project files:
• package.json (project configuration and dependencies)
• tsconfig.json (TypeScript configuration)
• App.tsx or App.jsx (root component)
• vite.config.ts or webpack.config.js (build configuration)
• Any existing .tsx or .jsx files in src/ folder
• Output: Confirm the detected application type is a React TypeScript or JavaScript project before proceeding.

Step 2 — Generate Code from Reference Files Only (REQUIRED)

• Before generating: Confirm that Steps 1 are complete
• Read the relevant references/*.md file(s) for the requested feature
• Cross-reference EVERY API, property, and method against these tables
• COMPONENT-BASED APPROACH (MANDATORY - REACT PATTERNS ONLY):
• Use JSX/TSX syntax for React component composition
• Configure all PDF Viewer properties directly as component props
• Use React hooks (useState, useRef, useEffect) when programmatic access is needed
• MANDATORY: Before generating ANY code, verify that reference files exist and are accessible
• Read the appropriate reference file(s) for the requested feature:
• Use read_file tool on relevant references/*.md files
• Confirm file contains Methods/Properties/Events tables
• Verify tables are complete and readable
• If reference file is missing or cannot be read:
• STOP code generation
• Respond: "Reference file for this feature is not available. Please ensure all reference files are present in the references/ directory."
• List the missing reference file name
• This is a BLOCKER step: Cannot proceed without reference file validation
• If an API/property does NOT appear in the reference file table, DO NOT USE IT
• Do NOT invent, guess, or suggest any API, method, property, class, or namespace not explicitly present in the reference files

---

Reference File Routing Guide

All templates and operation snippets live in references/*.md. Each file is a focused snippet or template the agent will combine when generating samples.

Flow: Always start with getting-started.md, then merge matched features into its anchors (PROPS, EVENTS, UI_BUTTONS, HANDLERS). If no keyword matches, return only the basic sample.

Checklist Before Generating Code

• [ ] Count the settings properties: 1-3? → Use inline | 4+? → Use constant
• [ ] Are enums involved? Yes → Must use typed constant with imports | No → Can use inline
• [ ] Is it reused elsewhere? Yes → Use constant | No → Prefer inline
• [ ] Do I need type safety? Yes → Import type { SettingsModel } | No → Skip type import
• [ ] Do I need enums? Yes → Import required enums | No → Skip enum imports
• [ ] Is the component prop simple enough? Yes → Keep inline | No → Extract to constant

🎯 Core Setup & Configuration

📐 Navigation() & Page Management

🔍 Viewing & Interaction

🛠️ Toolbar & Context Menu

Toolbar Configuration

⚠️ STRICT VALIDATION FOR TOOLBAR ITEM NAMES

When generating toolbar configurations, you MUST follow these rules to prevent incorrect toolbar item names:

1. ALWAYS reference exact item names from `toolbar-settings.md`

• Do NOT invent, guess, or assume toolbar item names
• Do NOT apply naming pattern logic to derive names
• Use ONLY names listed in the "Available Primary Toolbar Items", "Available Annotation Toolbar Items", and "Available Form Designer Items" sections in toolbar-settings.md

2. VALIDATE item names character-by-character

• Case sensitivity matters: HighlightTool ≠ HighlightOption
• Exact names only: AnnotationEditTool ≠ AnotatetionEditTool
• No abbreviations or shortcuts

3. Before generating toolbar configuration code:

• [ ] Open toolbar-settings.md reference file
• [ ] Locate: "Available Primary Toolbar Items" section
• [ ] Locate: "Available Annotation Toolbar Items" section
• [ ] Locate: "Available Form Designer Items" section
• [ ] Copy exact names from THESE SECTIONS ONLY
• [ ] Cross-check every single item name character-by-character
• [ ] If ANY item name is not in the reference sections, DO NOT USE IT
• [ ] Consult the "❌ COMMON MISTAKES TO AVOID" table in toolbar-settings.md if unsure

4. Common errors to prevent:

• ❌ AnotatetionEditTool → ✅ AnnotationEditTool (typo)
• ❌ CalibrationOption → ✅ CalibrateTool (wrong suffix)
• ❌ ShapeAnnotationOption → ✅ ShapeTool (annotation toolbar version)
• ❌ InkAnnotationOption → ✅ InkAnnotationTool (annotation toolbar version)
• For complete list of mistakes to avoid, see toolbar-settings.md "❌ COMMON MISTAKES TO AVOID" table

Context Menu Customization

📝 Annotations

📄 Forms

📋 Document Actions

⚙️ Advanced Features

Quick Start Example

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'>
        <PdfViewerComponent
          id="container"
          documentPath="https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf"
          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 />);

⚙️ SETTINGS CONFIGURATION BEST PRACTICES

When generating code with settings (toolbarSettings, annotationSettings, annotationSelectorSettings, arrowSettings, rectangleSettings, etc.), follow these guidelines to prevent unnecessary imports and over-engineering:

Rule 1: Simple Settings → Define INLINE in Component Props

Use this approach when:

• Configuring only 1-3 properties
• Settings are straightforward without complex enums or custom types
• No need for TypeScript typed constants

Example (DO THIS):

<PdfViewerComponent
  id="container"
  documentPath="https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf"
  annotationSelectorSettings={{
    selectionBorderColor: '#0000ff',
    selectionBorderThickness: 2,
    resizerBorderColor: '#ff0000',
    resizerFillColor: '#4070ff',
    resizerSize: 8,
  }}
  style={{ height: '640px' }}
>
  <Inject services={[Annotation]} />
</PdfViewerComponent>

Benefits:

• ✅ No extra imports needed
• ✅ Simple and readable
• ✅ Less code clutter
• ✅ Type checking still works

---

Rule 2: Complex Settings → Define as Typed Constant (OUTSIDE component)

Use this approach when:

• Configuring 4+ properties OR multiple related settings
• Using enums or complex configurations
• Need to reuse the same configuration across multiple components
• Settings are complex enough to warrant separate definition

Example (DO THIS ONLY FOR COMPLEX CASES):

import { PdfViewerComponent, Inject, Annotation } from '@syncfusion/ej2-react-pdfviewer';
import type { AnnotationSelectorSettingsModel } from '@syncfusion/ej2-react-pdfviewer';
import { AnnotationResizerLocation, CursorType } from '@syncfusion/ej2-react-pdfviewer';

// Define constant OUTSIDE component with proper types and enums
const annotationSelectorConfig: AnnotationSelectorSettingsModel = {
  selectionBorderColor: '#0000ff',
  selectionBorderThickness: 2,
  resizerBorderColor: '#ff0000',
  resizerFillColor: '#4070ff',
  resizerSize: 8,
  resizerShape: 'Square',
  selectorLineDashArray: [5, 6],
  resizerLocation: AnnotationResizerLocation.Corners | AnnotationResizerLocation.Edges,
  resizerCursorType: CursorType.grab,
};

export function App() {
  return (
    <PdfViewerComponent
      id="container"
      documentPath="https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf"
      annotationSelectorSettings={annotationSelectorConfig}
      style={{ height: '640px' }}
    >
      <Inject services={[Annotation]} />
    </PdfViewerComponent>
  );
}

When to import types and enums:

• [ ] Import type { SettingsNameModel } for TypeScript type checking
• [ ] Import any enums that are used in the settings (e.g., AnnotationResizerLocation, CursorType)
• [ ] Keep imports minimal - import ONLY what is used in the settings

Benefits:

• ✅ Type-safe configuration
• ✅ Proper enum usage
• ✅ Reusable across multiple components
• ✅ Clean component code

---

Rule 3: NEVER Over-Engineer Simple Cases

❌ DO NOT DO THIS (Over-engineered):

import { PdfViewerComponent, Inject, Annotation } from '@syncfusion/ej2-react-pdfviewer';
import type { ToolbarSettingsModel } from '@syncfusion/ej2-react-pdfviewer';

// Unnecessary constant for 2 simple properties
const toolbarSettings: ToolbarSettingsModel = {
  showTooltip: true,
};

export function App() {
  return (
    <PdfViewerComponent
      toolbarSettings={toolbarSettings}
      // ... rest of props
    />
  );
}

✅ DO THIS INSTEAD (Simple & Clean):

<PdfViewerComponent
  toolbarSettings={{ showTooltip: true }}
  // ... rest of props
/>

---

Syncfusion React PDF Viewer — Skill

Overview

The syncfusion-react-pdf-viewer skill enables AI-assisted code generation for the Syncfusion React PDF Viewer (`PdfViewerComponent`). It produces minimal, copy-pasteable TSX/JSX code to embed, configure, and interact with PDF documents inside React applications.

---

Compatibility

---

Skill Structure

syncfusion-react-pdfviewer/
├── SKILL.md                      # Skill rules, routing, and code generation guidelines
├── README.md                     # This file
└── references/
    ├── getting-started.md        # Minimal setup & initialization template
    ├── general-properties.md     # Core viewer properties (documentPath, height, locale, etc.)
    ├── enable-properties.md      # Feature toggle properties (enableToolbar, enableAnnotation, etc.)
    ├── toolbar-settings.md       # Toolbar visibility and item customization
    ├── toolbar-methods.md        # Programmatic toolbar show/hide at runtime
    ├── contextmenu.md            # Right-click context menu customization
    ├── page-navigation.md        # Navigate between pages programmatically
    ├── bookmark-navigation.md    # Bookmark panel and navigation
    ├── thumbnail-navigation.md   # Thumbnail panel and page previews
    ├── hyperlink-navigation.md   # Hyperlink and external link behavior
    ├── magnification.md          # Zoom levels, zoom modes, fit-to-page/width
    ├── interaction-mode.md       # Selection mode vs. panning mode
    ├── text-selection.md         # Enable text select, copy, and selection events
    ├── text-search.md            # Find text in PDF with search options
    ├── annotation-settings.md    # Annotation appearance (colors, opacity, styles)
    ├── annotation-events.md      # Annotation lifecycle events (add, delete, resize, etc.)
    ├── shape-label-settings.md   # Shape/measure annotation label customization
    ├── redaction-annotation.md   # Redaction: create, configure, and apply
    ├── form-field-settings.md    # Form field default properties
    ├── form-field-events.md      # Form field interaction events (focus, blur, change)
    ├── download.md               # PDF download configuration
    ├── print.md                  # PDF print configuration
    ├── organize-pages.md         # Reorder, rotate, insert, remove, merge pages
    ├── api-methods.md            # Programmatic API (load, export, undo/redo, extract text)
    └── events.md                 # Complete PDF Viewer event reference

---

Quick Start

1. Create a React Project

# TypeScript
npm create vite@latest my-app -- --template react-ts
cd my-app

# JavaScript
npm create vite@latest my-app -- --template react
cd my-app

2. Install the Package

npm install @syncfusion/ej2-react-pdfviewer --save

3. Copy WebAssembly Resources

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

4. Add CSS Imports (src/index.css)

@import '../node_modules/@syncfusion/ej2-base/styles/material.css';
@import '../node_modules/@syncfusion/ej2-buttons/styles/material.css';
@import '../node_modules/@syncfusion/ej2-dropdowns/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-splitbuttons/styles/material.css';
@import '../node_modules/@syncfusion/ej2-pdfviewer/styles/material.css';

5. Basic Component (src/App.tsx)

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

function App() {
  return (
    <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>
  );
}

export default App;

6. Run the App

npm run dev

---

Available Services

Inject only the services your use-case requires to keep the bundle lean.

---

Reference File Routing

Use the table below to find the correct reference file for any feature request.

Core Setup

Navigation

Viewing & Interaction

Toolbar & Context Menu

Annotations

Forms

Document Actions

Advanced / API

---

Metadata

Annotation Events

Description: Annotation events in React PDF Viewer are triggered when annotations are added, removed, moved, resized, selected, or modified on PDF document pages. These events enable custom workflows and UI updates based on annotation interactions.

Table of Contents

• When to Use Annotation Events
• Choosing the Right Event
• How to Use Annotation Events
• Annotation Events Reference
• Annotation Object Reference
• Common Use Cases

---

When to Use Annotation Events

Guide users to implement annotation events when they need to:

• Track user interactions - Log annotation changes for audit trails, analytics, or compliance
• Implement custom workflows - Trigger actions when annotations are added, modified, or removed
• Build custom UI - Update properties panels, toolbars, or status displays based on annotation state
• Enforce business rules - Validate or restrict annotation placement, modifications, or deletions
• Synchronize data - Save annotation changes to a backend, sync across users, or update related data
• Enhance UX - Provide real-time feedback, tooltips, or guided workflows during annotation

Why events matter: The PDF Viewer fires events at key moments in the annotation lifecycle. By handling these events, users can extend the viewer's behavior without modifying its internals.

---

Choosing the Right Event

Help users select the appropriate event based on their goal:

Decision Pattern: If user needs to prevent an action → use beforeAdd* events with args.cancel. If user needs to react after an action → use lifecycle events like annotationAdd, annotationMove, annotationRemove.

---

How to Use Annotation Events

Annotation events allow you to respond to user interactions with annotations in the PDF Viewer. Each event provides detailed information about the annotation and the action performed.

Basic Event Handler Pattern

const eventHandler = (args: any): void => {
  // Handle the event
  console.log('Event triggered:', args);
};
// Attach event handler to PdfViewerComponent
<PdfViewerComponent
  annotationAdd={eventHandler}  // Example: Use specific event name like annotationAdd, annotationRemove, etc.
>
</PdfViewerComponent>

---

Annotation Events Reference

The following table lists all available annotation events. Use this reference to identify event names, understand what triggers them, and access the data they provide.

How to read this table:

• Event Name: The prop name to use on <PdfViewerComponent>
• Description: When the event fires during the annotation lifecycle
• Args: The TypeScript type of the event arguments object
• Args Properties: Key properties available in the event handler, including data types

Usage tip: Most events provide annotationId, pageIndex, and the complete annotation object. Use the annotation object to access all properties listed in the Annotation Object Reference section below.

---

Annotation Object Reference

Purpose: When event handlers receive an annotation object in their arguments, use this reference to understand which properties are available and how to access them.

When to consult this reference:

• User needs to read annotation properties (color, opacity, position, type)
• User wants to display annotation details in a custom UI
• User needs to filter or validate annotations based on specific properties
• User is building custom logic based on annotation state

Usage pattern: Access properties directly from the args.annotation object:

const onAnnotationSelect = (args: any): void => {
  const annotation = args.annotation;
  
  // Access common properties
  console.log('Type:', annotation.type);           // e.g., "FreeText", "Ink"
  
  // Type-specific properties
  if (annotation.type === 'FreeText') {
    console.log('Content:', annotation.content);   // Text content
  }
};

Property availability: Not all properties are present on all annotation types. Check type or subType to determine which type-specific properties are available.

Core Properties (Available on All Annotation Types)

Type-Specific Properties

Different annotation types expose additional properties. Check the type property to determine which properties are available.

Nested Object Structures

Many annotation properties are complex objects. Use these references to understand their structure and access nested properties.

Rect Object

Purpose: Represents the rectangular boundary of an annotation. Available via args.annotation.rect.

Usage example:

const rect = args.annotation.rect;
console.log(`Position: (${rect.left}, ${rect.top})`);
console.log(`Size: ${rect.width} x ${rect.height}`);

Review Object

Purpose: Contains review/approval status for annotations. Available via args.annotation.review.

Usage example:

if (args.annotation.review) {
  console.log('Review state:', args.annotation.review.state);
  console.log('Reviewed by:', args.annotation.review.author);
}

AnnotationSettings Object

Purpose: Configuration settings for the annotation. Available via args.annotation.annotationSettings.

Usage example:

if (args.annotation.annotationSettings?.isLock) {
  console.log('This annotation is locked');
}

AnnotationSelectorSettings Object

Purpose: Visual appearance settings for annotation selection handles and borders. Available via args.annotation.annotationSelectorSettings.

LabelSettings Object

Purpose: Styling configuration for annotation labels (used in shape and measurement annotations). Available via args.annotation.labelSettings.

Font Object

Purpose: Text formatting properties for free text annotations. Available via args.annotation.font.

Usage example:

if (args.annotation.type === 'FreeText') {
  const font = args.annotation.font;
  if (font.isBold) console.log('Text is bold');
  if (font.isItalic) console.log('Text is italic');
}

Calibrate Object

Purpose: Measurement calibration data for distance/area annotations. Available via args.annotation.calibrate.

Bounds Object

Purpose: Position and dimensions of an annotation. Available via args.annotation.bounds.

Usage example:

const bounds = args.annotation.bounds;
console.log(`Annotation at (${bounds.x}, ${bounds.y})`);
console.log(`Size: ${bounds.width} x ${bounds.height}`);

// Bounds provides multiple coordinate representations
console.log(`Alternative: left=${bounds.left}, top=${bounds.top}, right=${bounds.right}`);

VertexPoint Object

Purpose: Represents individual points in polygon-based annotations. Available via args.annotation.vertexPoints (array).

Usage example:

if (args.annotation.vertexPoints) {
  args.annotation.vertexPoints.forEach((point, index) => {
    console.log(`Point ${index}: (${point.x}, ${point.y})`);
  });
}

---

Common Use Cases

Purpose: Guide users through practical implementations that solve real-world requirements. Each example demonstrates a specific pattern and explains when to apply it.

How to use these examples: 1. Identify the user's requirement (audit logging, access control, custom UI, etc.) 2. Point them to the matching use case 3. Explain how to adapt the pattern to their specific needs 4. Highlight which event properties are essential for their scenario

---

1. Tracking Annotation Changes

User Need: Log user interactions, implement audit trails, or send analytics data.

When to recommend: User mentions "tracking", "logging", "audit", "analytics", "telemetry", or "history".

Pattern: Attach handlers to lifecycle events (annotationAdd, annotationMove, annotationRemove) and log relevant data.

const onAnnotationMove = (args: any): void => {
  // Track annotation movement for telemetry
  logEvent('annotation_moved', {
    annotationId: args.annotationId,
    page: args.pageIndex,
    timestamp: new Date().toISOString()
  });
};

<PdfViewerComponent annotationMove={onAnnotationMove} />

Why this works: annotationMove fires after the move completes, providing the final position. For real-time tracking during drag, use annotationMoving instead.

Key properties: annotationId (identifier), pageIndex (location), timestamp (when).

---

2. Preventing Certain Actions

User Need: Restrict annotation placement on specific pages (e.g., cover pages, signature pages) or enforce business rules.

When to recommend: User mentions "prevent", "restrict", "block", "validation", "business rules", or "access control".

Pattern: Use beforeAddFreeText event and set args.cancel = true to prevent the action.

Important: This is the only event that supports cancellation. Use it for validation before annotations are created.

const onBeforeAddFreeText = (args: any): void => {
  // Prevent free text annotation on first page (cover page)
  if (args.pageIndex === 0) {
    args.cancel = true;
    alert('Annotations are not allowed on the cover page.');
  }
};

<PdfViewerComponent beforeAddFreeText={onBeforeAddFreeText} />

Why this works: Setting args.cancel = true stops the annotation from being added. The event fires before the action completes, allowing intervention.

Limitation: Currently only available for beforeAddFreeText. For other annotation types, handle in annotationAdd and remove if invalid using deleteAnnotationById().

---

3. Accessing Annotation Properties

User Need: Display annotation details in a properties panel, inspector, or custom UI.

When to recommend: User mentions "properties panel", "inspector", "details view", "custom UI", or "show annotation info".

Pattern: Use annotationSelect to get the full annotation object when user selects an annotation, then display its properties.

const onAnnotationSelect = (args: any): void => {
  const annotation = args.annotation;
  console.log('Color:', annotation.color);  
  // Update UI with annotation properties
  updatePropertiesPanel(args.annotationId, annotation);
};

<PdfViewerComponent annotationSelect={onAnnotationSelect} />

Why this works: annotationSelect provides the complete annotation object with all properties. Reference the Annotation Object Reference above to see all available properties.

Key insight: Use args.isMultiSelect to detect if multiple annotations are selected, and args.annotationCollection to process them.

---

4. Validating Property Changes

User Need: Track specific property modifications for compliance, review workflows, or change detection.

When to recommend: User mentions "property changes", "detect modifications", "compliance", "track edits", or "change history".

Pattern: Use annotationPropertiesChange event with boolean flags to identify which properties changed.

const onAnnotationPropertiesChange = (args: any): void => {
  if (args.isColorChanged) {
    console.log('Annotation color changed to:', args.annotation.color);
  }
};

<PdfViewerComponent annotationPropertiesChange={onAnnotationPropertiesChange} />

Why this works: The event provides boolean flags (isColorChanged, isThicknessChanged, isOpacityChanged) so you can detect exactly what changed without comparing old/new values.

Key properties: Use args.annotation to access the updated property values.

Advanced: Combine with annotationSelect to show real-time property updates in a UI panel.

---

5. Handling Multiple Selections

User Need: Perform bulk operations on multiple annotations (delete all, change color, export selected).

When to recommend: User mentions "bulk operations", "multiple annotations", "select all", "batch processing", or "group actions".

Pattern: Check args.isMultiSelect in annotationSelect event and use args.annotationCollection to process each annotation.

const onAnnotationSelect = (args: any): void => {
  if (args.isMultiSelect) {
    console.log('Multiple annotations selected');
    console.log('Selected annotations count:', args.annotationCollection.length);
    
    // Process each selected annotation
    args.annotationCollection.forEach((annotation: any) => {
      console.log('Annotation ID:', annotation.annotationId);
    });
  } else {
    console.log('Single annotation selected:', args.annotationId);
  }
};
<PdfViewerComponent annotationSelect={onAnnotationSelect} />

Why this works: annotationCollection contains all selected annotations when isMultiSelect === true. Loop through this array to apply operations to each annotation.

Implementation tip: After bulk operations, use the viewer's API methods (e.g., deleteAnnotationById(), updateAnnotationProperties()) on each annotation ID from the collection.

UI consideration: Provide clear feedback showing how many annotations are selected and which operation will be applied.

Annotation Settings in React PdfViewer Component

Description: Configure PDF annotation settings immediately to control appearance, behavior, and interaction of text markup, shape, and stamp annotations in the SfPdfViewer component. Customize colors, styles, author details, and access restrictions to achieve specific annotation requirements

Table of Contents

• Overview
• Quick Start
• Global vs Type-Specific Settings
• Annotation Types Available
• Settings Properties Reference
• Annotation-Related Component Properties
• Core Properties for All Annotations
• Selector Customization
• Common Use Cases
• Type Definitions

Important: Bounds Format for Annotations (Lowercase)

⚠️ When adding annotations programmatically, ALWAYS use lowercase property names in the bounds object:

// CORRECT ✅ - Use LOWERCASE bounds
pdfViewerRef.current?.annotation.addAnnotation('Rectangle', {
  bounds: { x: 100, y: 100, width: 200, height: 50 },
  color: '#FF0000'
});

// INCORRECT ❌ - Do NOT use capitalized letters
pdfViewerRef.current?.annotation.addAnnotation('Rectangle', {
  bounds: { X: 100, Y: 100, Width: 200, Height: 50 },  // WRONG for annotations
  color: '#FF0000'
});

---

Overview

Configure annotation settings immediately to control how PDF annotations display and behave in your viewer. Choose between applying settings globally to all annotation types or customizing individual annotation behaviors through type-specific properties like highlightSettings, areaSettings, stampSettings, etc.

When to use: Whenever you need to customize annotation appearance (colors, size, opacity), control user interactions (lock state, allowed actions), set author details, or restrict features (disable downloads/printing).

How to Use the Settings in PDF Viewer

Quick Start

Apply Settings to Specific Annotation Type

Customize appearance and behavior for individual annotation types by setting type-specific properties:

const highlightSettings = { 
  color: 'green',           // Text highlight color
  opacity: 0.6,             // Transparency (0-1)
  author: 'John Doe',       // Who created the annotation
  isLock: false             // Allow user interaction
};

<PdfViewerComponent
  highlightSettings={highlightSettings}
>
  <Inject services={[Annotation, TextSelection]} />
</PdfViewerComponent>

Use this when: You need to control how a specific annotation type (highlight, underline, stamp, etc.) appears and behaves across your PDF.

Apply Global Settings to All Annotations

Use annotationSettings property to apply common settings across every annotation type at once:

const annotationSettings = { 
  author: 'PDF Author',
  opacity: 0.7,
  isLock: false
};

<PdfViewerComponent
  annotationSettings={annotationSettings}
>
  <Inject services={[Annotation]} />
</PdfViewerComponent>

Use this when: You want consistent author names, security levels, or opacity across all annotations in the PDF.

Global vs Type-Specific Settings

Global Settings (annotationSettings):

• Applied to all annotation types unless overridden
• Best for company-wide policies (author name, lock state, download restrictions)
• Properties: author, subject, customData, isLock, isPrint, skipDownload, skipPrint, maxWidth, maxHeight, minWidth, minHeight, opacity, allowedInteractions

Type-Specific Settings:

• Override global settings for individual annotation behaviors
• Best for controlling how each annotation type looks and acts
• Examples: highlightSettings, areaSettings, stampSettings, freeTextSettings
• Each type has unique properties (e.g., highlightSettings has enableMultiPageAnnotation, enableTextMarkupResizer)

Decision Guide:

• Setting author name? → Use annotationSettings (global)
• Customizing highlight color only? → Use highlightSettings (type-specific)
• Locking all annotations? → Use annotationSettings (global)
• Need different colors for different types? → Use multiple type-specific settings

Annotation Types Available

All supported annotation types and their corresponding settings properties:

Settings Properties Reference

Annotation-Related Component Properties

These properties are available directly on the PdfViewerComponent to control annotation-related functionality:

Core Properties for All Annotations

Common Use Cases

Use Case 1: Apply Company Branding to All Annotations

// All annotations created by users will show your company name
<PdfViewerComponent
  annotationSettings={{ 
    author: 'Acme Corporation',
    subject: 'Document Review',
    customData: { department: 'Legal', version: '1.0' }
  }}
>
  <Inject services={[Annotation]} />
</PdfViewerComponent>

Use Case 2: Make Annotations Non-Editable After Creation

// Users can see annotations but cannot modify them
<PdfViewerComponent
  annotationSettings={{ 
    isLock: true,           // Prevent editing
    allowedInteractions: [] // Restrict all interactions
  }}
>
  <Inject services={[Annotation]} />
</PdfViewerComponent>

Use Case 3: Customize Highlight and Underline Appearance

// Make highlights green and underlines blue
<PdfViewerComponent
  highlightSettings={{ color: '#00FF00', opacity: 0.5 }}
  underlineSettings={{ color: '#0000FF', opacity: 0.4 }}
>
  <Inject services={[Annotation, TextSelection]} />
</PdfViewerComponent>

Use Case 4: Restrict Annotation Download/Print

// Annotations won't appear in exported files or print output
<PdfViewerComponent
  annotationSettings={{ 
    skipDownload: true,  // Hide from downloaded PDFs
    skipPrint: true      // Hide from printed pages
  }}
>
  <Inject services={[Annotation]} />
</PdfViewerComponent>

Use Case 5: Customize Resize Handles When Editing Annotations

// Control how annotation selection handles appear during editing
<PdfViewerComponent
  annotationSelectorSettings={{ 
    resizerBorderColor: '#FF0000',    // Red border
    resizerFillColor: '#FFE0E0',      // Light red fill
    resizerSize: 8,                   // Handle size in pixels
    resizerShape: 'Circle'            // Circle or Square
  }}
>
  <Inject services={[Annotation]} />
</PdfViewerComponent>

Selector Customization

Apply Selection Styling Globally

Apply resize handle customization to all annotations:

<PdfViewerComponent
  annotationSelectorSettings={{ resizerBorderColor: 'green' }}
>
  <Inject services={[Annotation]} />
</PdfViewerComponent>

Apply Selection Styling to Specific Annotation Type

Customize resize handles for individual annotation types:

<PdfViewerComponent
  areaSettings={{ annotationSelectorSettings: { resizerBorderColor: 'green' } }}
>
  <Inject services={[Annotation]} />
</PdfViewerComponent>

Type Definitions

AnnotationSelectorSettings

CursorType

AnnotationResizerLocation

AnnotationResizerShape

LineHeadStyle

CustomStampSettings

FontStyle

TextAlignment

CalibrationUnit

DynamicStampItem

SignStampItem

StandardBusinessStampItem

API Methods in React PdfViewer Component

When user requests programmatic control beyond UI interactions, guide them to these API methods. This reference helps you recommend the right method based on user goals: loading documents, managing form fields, handling annotations, exporting data, or manipulating viewer state.

Your role: Match user intent to appropriate API methods, explain when to use each method, and provide complete working examples.

Table of Contents

• When to Use These APIs
• API Categories
• Complete API Reference
• Common Parameter Types
• Usage Examples by Scenario

When to Use These APIs

Guide user to these methods when they express these needs:

• "Load a PDF programmatically" → Use load() and unload() methods
• "Process form data from PDF" → Use exportFormFieldsAsObject() or importFormFields()
• "Add/edit PDF annotations dynamically" → Use addAnnotation(), deleteAnnotations(), exportAnnotation()
• "Extract text from PDF" → Use extractText() with bounds parameter
• "Implement undo/redo for PDF edits" → Use undo() and redo() methods
• "Respond to layout changes" → Use updateViewerContainer() after resize
• "Navigate to specific coordinates" → Use zoomToRect() or coordinate conversion methods

Alternative approaches: If user needs simple page navigation or UI interactions, refer to navigation.md or events.md instead of programmatic APIs.

API Categories

When user describes their goal, identify which category fits best, then recommend specific methods:

Complete API Reference

How to use this reference: When user describes what they want to do, scan this table for matching methods. Then provide complete code examples with error handling and explain why that method fits their use case.

The table below lists all available methods - use it to recommend the right API based on user intent, not as copy-paste reference material.

List of Methods

Common Parameter Types

When constructing method calls, guide user on parameter structure. Many methods require specific object types - reference these schemas when building examples.

⚠️ CRITICAL: Bounds Format Differs Between Annotations and Form Fields

IMPORTANT - These two APIs have DIFFERENT bounds property casing:

Annotations – bounds (lowercase):

pdfViewerRef.current?.annotation.addAnnotation('Rectangle', {
  bounds: { x: 100, y: 100, width: 200, height: 50 }
});

Form Fields – bounds (capitalized):

pdfViewerRef.current?.formDesigner.addFormField('Textbox', {
  bounds: { X: 100, Y: 100, Width: 200, Height: 30 }
});

Do NOT mix or interchange these formats - each API expects its specific casing

---

IPoint

When to use: Methods involving coordinates (click detection, point conversion). Used for coordinate points in the PDF viewer.

IRect

When to use: Methods involving regions (text extraction, zoom to area). Used for rectangular regions in the PDF document.

PageInfo

When to use: Returned by getPageInfo() - use for dynamic layout calculations. Contains information about a specific page in the PDF document.

FormField

When to use: Working with form field methods (retrieve, update, export). Represents a form field in the PDF document.

PdfAnnotationBase

When to use: Required parameter for addAnnotation() method. Base class for PDF annotations.

CustomToolbarItem

When to use: Required parameter for addCustomMenu() method. Represents a custom toolbar menu item.

AnnotationType

When to use: Used with annotation module methods to specify annotation types. Valid annotation types include:

• 'None' - No annotation
• 'Highlight' - Text highlight annotation
• 'Underline' - Text underline annotation
• 'Strikethrough' - Text strikethrough annotation
• 'Squiggly' - Text squiggly underline annotation
• 'Line' - Line annotation
• 'Arrow' - Arrow annotation
• 'Rectangle' - Rectangle shape annotation
• 'Circle' - Circle shape annotation
• 'Polygon' - Polygon shape annotation
• 'Distance' - Distance measurement annotation
• 'Perimeter' - Perimeter measurement annotation
• 'Area' - Area measurement annotation
• 'Radius' - Radius measurement annotation
• 'Volume' - Volume measurement annotation
• 'FreeText' - Free text annotation
• 'HandWrittenSignature' - Handwritten signature annotation
• 'Ink' - Ink annotation (freehand drawing)
• 'Stamp' - Stamp annotation
• 'Image' - Image stamp annotation
• 'StickyNotes' - Sticky notes annotation

AnnotationSettings

When to use: Optional parameter for annotation.addAnnotation() to customize annotation properties. Annotation settings object can include:

FormFieldType

When to use: Used with form designer module methods to specify form field types. Valid form field types include:

• 'Textbox' - Text input field
• 'Password' - Password input field
• 'Checkbox' - Checkbox field
• 'RadioButton' - Radio button field
• 'DropDown' - Dropdown list field
• 'ListBox' - List box field
• 'SignatureField' - Signature field
• 'InitialField' - Initial field

FormFieldSettings

When to use: Used with form designer methods to configure form field properties. Form field settings object can include:

CustomStamp

When to use: Used to define custom stamp images for the PDF Viewer. Custom stamp object structure:

AnnotationDrawingOptions

When to use: Used to configure annotation drawing behavior with angular constraints. Annotation drawing options object:

Usage Examples by Scenario

Use these patterns when user describes matching scenarios. Provide complete examples with error handling and explain why this approach fits their needs.

Scenario 1: Load and Download PDF

When: User needs to open a PDF file and allow downloading it.

Why: Use load() for dynamic document switching and download() to save modified PDFs client-side without server roundtrip.

// Load a PDF document
pdfViewerRef.current?.load('loaded document.pdf');
// Later, allow user to download
pdfViewerRef.current?.download();

Scenario 2: Manage Interactive Form Fields

When: Working with fillable PDFs that have form fields (text inputs, checkboxes).

Why: Use retrieveFormFields() to read current state, updateFormFieldsValue() for programmatic pre-fill (e.g., from database), and exportFormFieldsAsObject() for structured data submission.

// Retrieve all form fields
const formFields = pdfViewerRef.current?.retrieveFormFields();
// Update specific field values
pdfViewerRef.current?.updateFormFieldsValue('firstName', 'John');
pdfViewerRef.current?.updateFormFieldsValue('email', 'john@example.com');
// Export filled form data
const formData = pdfViewerRef.current?.exportFormFieldsAsObject();
console.log(formData);

Scenario 3: Work with Annotations

When: Adding comments, highlights, or other markup to PDFs.

Why: Use exportAnnotation() to save user markup for later sessions, importAnnotation() to restore saved annotations, and deleteAnnotations() for programmatic cleanup.

// Export current annotations
const annotations = pdfViewerRef.current?.exportAnnotation();
// Import previously saved annotations
pdfViewerRef.current?.importAnnotation(annotationJSON);
// Delete specific annotation
pdfViewerRef.current?.deleteAnnotations('annotation-id-123');

Scenario 4: Extract Text from PDF

When: You need to get text content from a specific region.

Why: Use extractText() with bounds parameter for targeted text extraction - ideal for processing specific fields, copying text from coordinates, or building search/highlight features.

// Extract text from a rectangular region
const bounds = { x: 100, y: 150, width: 200, height: 100 };
const extractedText = pdfViewerRef.current?.extractText(bounds);
console.log('Extracted:', extractedText);

Scenario 5: Navigate and Zoom

When: Programmatically moving to specific pages or zooming regions.

Why: Use getPageInfo() for dynamic layout calculations and zoomToRect() to focus on specific regions (e.g., highlighting search results, focusing on form fields).

// Get page information
const pageInfo = pdfViewerRef.current?.getPageInfo(0);
console.log('Page dimensions:', pageInfo?.width, pageInfo?.height);

// Zoom to specific rectangular area
const rect = { x: 50, y: 50, width: 300, height: 300 };
pdfViewerRef.current?.zoomToRect(rect);

Scenario 6: Implement Undo/Redo

When: Allowing users to undo/redo annotations or form changes.

Why: Use undo() and redo() to provide familiar editing experience - essential for annotation workflows where users need to revert mistakes.

// User clicks undo button
pdfViewerRef.current?.undo();
// User clicks redo button
pdfViewerRef.current?.redo();

Scenario 7: Custom UI Integration

When: Adding custom menu items or notifications.

Why: Use addCustomMenu() to extend context menu with app-specific actions (e.g., "Send to Email", "Share") and showNotificationPopup() for in-viewer feedback without blocking dialogs.

// Add custom context menu item
const customItems = [
  { id: 'custom-1', text: 'My Action', tooltipText: 'Do something custom' }
];
pdfViewerRef.current?.addCustomMenu(customItems, 'target-element-id');
// Show notification
pdfViewerRef.current?.showNotificationPopup('PDF loaded successfully', 3000);

Scenario 8: Programmatic Annotation Management

When: You need to add, select, edit, or manage annotations programmatically without user interaction.

Why: Use the annotation module methods to create annotations dynamically (e.g., highlighting search results), programmatically select/edit annotations, or set annotation mode for user drawing.

• Note: Pagenumber is starts from 1.

// Add a highlight annotation programmatically
pdfViewerRef.current?.annotation.addAnnotation('Highlight', {
  bounds: { x: 100, y: 100, width: 200, height: 50 },
  pageNumber: 0,color: '#FFFF00',opacity: 0.5,author: 'System',
  subject: 'Auto-highlight',note: 'Important section'
});
// Select an existing annotation by ID
pdfViewerRef.current?.annotation.selectAnnotation('annotation-id-123');
// Edit an existing annotation's properties
pdfViewerRef.current?.annotation.editAnnotation({
  id: 'annotation-id-123',color: '#FF0000',opacity: 0.8, note: 'Updated comment'
});
// Set annotation mode for user to add rectangles
pdfViewerRef.current?.annotation.setAnnotationMode('Rectangle');
// Clear current annotation selection
pdfViewerRef.current?.annotation.clearSelection();
// Convert color formats
const rgbaColor = pdfViewerRef.current?.annotation.hexToRgba('#FF5733');
console.log('RGBA Color:', rgbaColor);

Ink Annotation with Path Points (Freehand Drawing):

const viewer = getViewer();
// Add ink annotation with SVG path data representing freehand drawing
viewer?.annotation.addAnnotation('Ink', {
  offset: { x: 150, y: 100 }, pageNumber: 1, width: 200, height: 60,
  path: '[{"command":"M","x":244.83,"y":982.00},{"command":"L","x":250.83,"y":953.33},{"command":"L","x":260.83,"y":920.33}]', strokeColor: '#0000FF', thickness: 2,opacity: 1, author: 'User'
});

Scenario 9: Dynamic Form Field Creation and Management

When: Creating fillable PDF forms programmatically or modifying existing form fields.

Why: Use the formDesigner module to dynamically add form fields (textboxes, checkboxes, dropdowns), select/modify form fields, or enable form field drawing mode.

// Add a textbox form field programmatically
const textboxElement = pdfViewerRef.current?.formDesigner.addFormField('Textbox', {
  name: 'firstName', bounds: { x: 100, y: 100, width: 200, height: 30 },
  value: '', fontSize: 12,fontFamily: 'Helvetica',color: '#000000', backgroundColor: '#FFFFFF',
  borderColor: '#000000', thickness: 1,isRequired: true,tooltip: 'Enter your first name'
});
// Add a checkbox form field
pdfViewerRef.current?.formDesigner.addFormField('Checkbox', {
  name: 'agreeTerms',bounds: { x: 100, y: 150, width: 20, height: 20 }, isChecked: false,
  borderColor: '#000000',backgroundColor: '#FFFFFF'
});
// Add a dropdown form field with options
pdfViewerRef.current?.formDesigner.addFormField('DropDown', {
  name: 'country', bounds: { x: 100, y: 200, width: 200, height: 30 },
  options: [
    { itemName: 'USA', itemValue: 'us' }, { itemName: 'Canada', itemValue: 'ca' }, { itemName: 'UK', itemValue: 'uk' }
  ], fontSize: 12, fontFamily: 'Helvetica'
});
// Select a form field for editing
pdfViewerRef.current?.formDesigner.selectFormField('firstName');
// Update existing form field properties
pdfViewerRef.current?.formDesigner.updateFormField('firstName', {
  backgroundColor: '#FFFF00',
  fontSize: 14,
  value: 'John'
});
// Reset a form field to original state
pdfViewerRef.current?.formDesigner.resetFormField('firstName');
// Delete a form field
pdfViewerRef.current?.formDesigner.deleteFormField('firstName', true);
// Set form field mode for user to add textboxes
pdfViewerRef.current?.formDesigner.setFormFieldMode('Textbox');
// Clear form field selection
pdfViewerRef.current?.formDesigner.clearSelection('firstName');
// Convert RGB to Hex color
const hexColor = pdfViewerRef.current?.formDesigner.getRgbToHex({r: 255, g: 87, b: 51});
console.log('Hex Color:', hexColor);

Scenario 10: Custom Stamps Configuration

When: Adding custom stamp images to the PDF Viewer stamp menu.

Why: Use custom stamps to provide organization-specific stamps (company logo, approval stamps, etc.) that users can add to PDFs.

function App() {
  const customStamps = [
    {
      customStampName: 'Approved', customStampImageSource: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...'
    },
    {
      customStampName: 'Confidential', customStampImageSource: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...'
    }
  ];
  return (
    <PdfViewerComponent customStamp={customStamps}/>
  );
}

Scenario 11: Annotation Drawing with Angular Constraints

When: You want to restrict line and arrow annotations to specific angles for precise diagrams.

Why: Use annotationDrawingOptions to enable angular constraints, making it easier to draw perfectly horizontal, vertical, or angled lines.

function App() {
  const annotationDrawingOptions = {
    enableLineAngleConstraints: true,
    restrictLineAngleTo: 45  // Lines snap to 0°, 45°, 90°, 135°, etc.
  };
  return (
    <PdfViewerComponent annotationDrawingOptions={annotationDrawingOptions}/>
  );
}

---

Bookmark Navigation

Brief: Bookmark navigation enables users to navigate through embedded PDF bookmarks. The React PDF Viewer automatically loads and presents bookmarks for easy document traversal.

⚠️ CRITICAL: Correct API Usage

ALL bookmark methods MUST be accessed via `pdfViewerRef.current.bookmark` module:

// ✅ CORRECT - Access via bookmark module
pdfViewerRef.current.bookmark.openBookmarkPane();
pdfViewerRef.current.bookmark.closeBookmarkPane();
pdfViewerRef.current.bookmark.getBookmarks();
pdfViewerRef.current.bookmark.goToBookmark(pageIndex, y);

// ❌ WRONG - These methods DO NOT exist on pdfViewerRef.current
pdfViewerRef.current.openBookmarkPanel();    // ❌ NOT A VALID METHOD
pdfViewerRef.current.closeBookmarkPanel();   // ❌ NOT A VALID METHOD
pdfViewerRef.current.openBookmarkPane();     // ❌ WRONG - Missing .bookmark
pdfViewerRef.current.closeBookmarkPane();    // ❌ WRONG - Missing .bookmark

Table of Contents

• When to Use
• Prerequisites
• Enabling Bookmarks
• API Methods
• Complete Examples
• Bookmark Data Structure
• Best Practices

When to Use

Use bookmarks when:

• Jump to specific sections in long PDFs (reports, manuals, specifications)
• Navigate document hierarchy without manual scrolling
• Display table of contents extracted from PDF
• Build custom navigation UIs beyond default sidebar

Skip bookmarks if PDF has no embedded bookmarks or only needs simple page navigation.

Prerequisites

Before using bookmark features, ensure:

• enableBookmark={true} is set on the PdfViewerComponent
• BookmarkView service is injected into the component
• The PDF document contains embedded bookmarks (many don't)

Enabling Bookmarks

<PdfViewerComponent
  ref={viewerRef}
  enableBookmark={true}
  documentPath="document.pdf"
>
  <Inject services={[BookmarkView]} />
</PdfViewerComponent>

What happens: Bookmarks load automatically, sidebar panel appears with hierarchy, and all bookmark API methods become available.

API Methods

1. openBookmarkPane()

Signature: pdfViewerRef.current.bookmark.openBookmarkPane(): void

Opens the bookmark panel in the left sidebar.

const openBookmark = () => {
  if (viewerRef.current && viewerRef.current.bookmark) {
    viewerRef.current.bookmark.openBookmarkPane();
  }
};

2. closeBookmarkPane()

Signature: pdfViewerRef.current.bookmark.closeBookmarkPane(): void

Closes the bookmark panel.

const closeBookmark = () => {
  if (viewerRef.current && viewerRef.current.bookmark) {
    viewerRef.current.bookmark.closeBookmarkPane();
  }
};

3. getBookmarks()

Signature: pdfViewerRef.current.bookmark.getBookmarks(): any

Retrieves all bookmarks as hierarchical array. Returns [] if no bookmarks exist.

const [bookmarks, setBookmarks] = React.useState([]);

React.useEffect(() => {
  const timer = setTimeout(() => {
    if (viewerRef.current && viewerRef.current.bookmark) {
      const allBookmarks = viewerRef.current.bookmark.getBookmarks();
      setBookmarks(allBookmarks || []);
    }
  }, 1000); // Wait for PDF to load
  return () => clearTimeout(timer);
}, []);

4. goToBookmark()

Signature: pdfViewerRef.current.bookmark.goToBookmark(pageIndex: number, y: number): boolean

Navigates to specific page and Y coordinate. Returns true if successful.

Parameters:

• pageIndex (number): Zero-based page index (0 = first page)
• y (number): Vertical pixel coordinate (0 = top of page)

const navigateToBookmark = (bookmark) => {
  if (viewerRef.current && viewerRef.current.bookmark) {
    const success = viewerRef.current.bookmark.goToBookmark(bookmark.page, bookmark.y);
    if (!success) {
      console.error('Navigation failed');
    }
  }
};

Complete Examples

Example 1: Open/Close Buttons

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

export function App() {
  const viewerRef = useRef(null);
  
  const openBookmark = () => {
    if (viewerRef.current && viewerRef.current.bookmark) {
      viewerRef.current.bookmark.openBookmarkPane();
    }
  };

  const closeBookmark = () => {
    if (viewerRef.current && viewerRef.current.bookmark) {
      viewerRef.current.bookmark.closeBookmarkPane();
    }
  };
  
  return (
    <div>
      <div style={{ marginBottom: '10px' }}>
        <button onClick={openBookmark} style={{ marginRight: '10px' }}>
          Open Bookmarks
        </button>
        <button onClick={closeBookmark}>
          Close Bookmarks
        </button>
      </div>
      <PdfViewerComponent
        ref={viewerRef}
        documentPath="https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf"
        enableBookmark={true}
        style={{ height: '640px' }}
      >
        <Inject services={[BookmarkView]} />
      </PdfViewerComponent>
    </div>
  );
}

Example 2: Toggle Button

const [isPaneOpen, setIsPaneOpen] = React.useState(false);

const toggleBookmarks = () => {
  if (viewerRef.current && viewerRef.current.bookmark) {
    if (isPaneOpen) {
      viewerRef.current.bookmark.closeBookmarkPane();
    } else {
      viewerRef.current.bookmark.openBookmarkPane();
    }
    setIsPaneOpen(!isPaneOpen);
  }
};

<button onClick={toggleBookmarks}>
  {isPaneOpen ? 'Hide Bookmarks' : 'Show Bookmarks'}
</button>

Example 3: Auto-Open on Load

const handleDocumentLoad = () => {
  if (viewerRef.current && viewerRef.current.bookmark) {
    viewerRef.current.bookmark.openBookmarkPane();
  }
};

<PdfViewerComponent
  ref={viewerRef}
  documentPath="document.pdf"
  enableBookmark={true}
  documentLoad={handleDocumentLoad}
>
  <Inject services={[BookmarkView]} />
</PdfViewerComponent>

Example 4: Custom Bookmark Sidebar

const [bookmarks, setBookmarks] = React.useState([]);

React.useEffect(() => {
  const timer = setTimeout(() => {
    if (viewerRef.current && viewerRef.current.bookmark) {
      const allBookmarks = viewerRef.current.bookmark.getBookmarks();
      setBookmarks(allBookmarks || []);
    }
  }, 1000);
  return () => clearTimeout(timer);
}, []);

const handleBookmarkClick = (bookmark) => {
  if (viewerRef.current && viewerRef.current.bookmark) {
    viewerRef.current.bookmark.goToBookmark(bookmark.page, bookmark.y);
  }
};

return (
  <div style={{ display: 'flex', height: '100vh' }}>
    <div style={{ width: '250px', overflowY: 'auto' }}>
      <h3>Table of Contents</h3>
      {bookmarks.length > 0 ? (
        <ul>
          {bookmarks.map((bm, i) => (
            <li key={i}>
              <button onClick={() => handleBookmarkClick(bm)}>
                {bm.title}
              </button>
            </li>
          ))}
        </ul>
      ) : (
        <p>No bookmarks</p>
      )}
    </div>
    <div style={{ flex: 1 }}>
      <PdfViewerComponent
        ref={viewerRef}
        documentPath="document.pdf"
        enableBookmark={true}
      >
        <Inject services={[BookmarkView]} />
      </PdfViewerComponent>
    </div>
  </div>
);

Bookmark Data Structure

Each bookmark object returned by getBookmarks() has:

[
  {
    title: "Chapter 1",
    page: 0,
    y: 150,
    children: [
      { title: "Section 1.1", page: 2, y: 200, children: [] },
      { title: "Section 1.2", page: 5, y: 100, children: [] }
    ]
  },
  {
    title: "Chapter 2",
    page: 10,
    y: 50,
    children: []
  }
]

Bookmark Properties

The following property is available on the PdfViewerComponent to control bookmark panel state:

Usage Example

<PdfViewerComponent
  ref={viewerRef}
  enableBookmark={true}
  isBookmarkPanelOpen={true}
  documentPath="document.pdf"
>
  <Inject services={[BookmarkView]} />
</PdfViewerComponent>

When to use `isBookmarkPanelOpen`:

• Programmatically open the bookmark panel on document load
• Control panel visibility based on document type or user preferences
• Set default panel state for specific workflows
• Implement custom bookmark panel toggle buttons

Example - Auto-open bookmarks for long documents:

const handleDocumentLoad = () => {
  if (viewerRef.current.pageCount > 30) {
    // Auto-open bookmark panel for documents with more than 30 pages
    viewerRef.current.isBookmarkPanelOpen = true;
  }
};

<PdfViewerComponent
  ref={viewerRef}
  enableBookmark={true}
  documentLoad={handleDocumentLoad}
>
  <Inject services={[BookmarkView]} />
</PdfViewerComponent>

---

Best Practices

1. Always validate references before calling methods:

   if (viewerRef.current && viewerRef.current.bookmark) {
     viewerRef.current.bookmark.openBookmarkPane();
   }

2. Wait for PDF to load before accessing bookmarks:

• Use setTimeout (1-1.5s delay) or documentLoad event

   React.useEffect(() => {
     const timer = setTimeout(() => {
       const bookmarks = viewerRef.current?.bookmark.getBookmarks();
       setBookmarks(bookmarks || []);
     }, 1000);
     return () => clearTimeout(timer);
   }, []);

3. Handle PDFs with no bookmarks gracefully:

• getBookmarks() returns [] if no bookmarks exist

   {bookmarks.length > 0 ? renderBookmarks() : <p>No bookmarks</p>}

4. Cache bookmarks in state:

• Call getBookmarks() once on load, store in useState, reuse

5. Validate data before navigation:

   if (typeof bookmark.page === 'number' && typeof bookmark.y === 'number') {
     viewerRef.current.bookmark.goToBookmark(bookmark.page, bookmark.y);
   }