Guides

Annotations

The ComPDF React Native SDK supports multiple annotation event listeners to help you customize annotation interaction behaviors in your React Native application.

Event Overview

Event Name	Trigger Timing	Return Value
onAnnotationCreationPrepared	When preparing to create signature, stamp, link, or image annotations	Annotation type
onInterceptAnnotationAction	When clicking note or link annotations	CPDFAnnotation object
CPDFEvent.ANNOTATIONS_CREATED	When creating annotations	Created annotation data
CPDFEvent.ANNOTATIONS_SELECTED	When selecting annotations	Selected annotation data
CPDFEvent.ANNOTATIONS_DESELECTED	When deselecting annotations	Deselected annotation data

Annotation Creation Prepared Callback

Callback method: onAnnotationCreationPrepared

This callback is triggered when the user clicks signature, stamp, link, or image tools in the bottom toolbar, or calls pdfReaderRef.current.setAnnotationMode() to enter creation mode.

Through this callback, you can display custom selection dialogs in your React Native application instead of using ComPDF's built-in selection dialogs.

Configuration

To use this feature, disable the default selection dialogs in CPDFConfiguration:

ComPDFKit.getDefaultConfig({
  annotationsConfig: {
    autoShowSignPicker: false,   // Disable signature selection dialog
    autoShowLinkDialog: false,   // Disable link selection dialog
    autoShowPicPicker: false,    // Disable image selection dialog
    autoShowStampPicker: false,  // Disable stamp selection dialog
  }
})

Listen to Callback

<CPDFReaderView
  ref={pdfReaderRef}
  document={samplePDF}
  configuration={configuration}
  onAnnotationCreationPrepared={(type, annotation) => {
    // Signature, stamp, image annotations: triggered when entering creation mode
    // Link annotations: triggered after user draws a rectangle on the page
    console.log('Preparing to create annotation of type:', type);
    // Display custom selection dialog here
  }}
/>

Insert Signature

After selecting a signature image, call the following API to insert a signature annotation:

await pdfReaderRef.current?.prepareNextSignature('/path/to/signature.png');

Insert Stamp

After selecting a stamp, call the corresponding API based on stamp type:

// Standard stamp (see CPDFStandardStamp enum for available types)
await pdfReaderRef.current?.prepareNextStamp({ standardStamp: CPDFStandardStamp.Approved });

// Image stamp
await pdfReaderRef.current?.prepareNextStamp({ imagePath: '/path/to/stamp.png' });

// Text stamp
await pdfReaderRef.current?.prepareNextStamp({
  textStamp: {
    content: 'ComPDF-ReactNative',
    date: CPDFDateUtil.getTextStampDate({ timeSwitch: false, dateSwitch: true }),
    shape: CPDFTextStampShape.none,
    color: CPDFTextStampColor.white,
  },
});

Annotation Action Intercept Callback

Callback method: onInterceptAnnotationAction

This callback is triggered when the user clicks a note or link annotation, returning a CPDFAnnotation object. Through this callback, you can intercept the default click behavior in the React Native layer to implement custom interaction logic.

Configuration

To use this feature, enable interception of default annotation click behaviors in CPDFConfiguration:

ComPDFKit.getDefaultConfig({
  annotationsConfig: {
    interceptNoteAction: true,  // Intercept note default action
    interceptLinkAction: true,  // Intercept link default action
  }
})

Listen to Callback

<CPDFReaderView
  ref={pdfReaderRef}
  document={samplePDF}
  configuration={configuration}
  onInterceptAnnotationAction={(annotation) => {
    console.log('Intercepted annotation action:', annotation.type);
    // Customize click behavior based on annotation type
    if (annotation.type === CPDFAnnotationType.NOTE) {
      // Custom note click handling
    } else if (annotation.type === CPDFAnnotationType.LINK) {
      // Custom link click handling
    }
  }}
/>

Annotation Created Event

Event name: CPDFEvent.ANNOTATIONS_CREATED

Triggered when the user creates an annotation, listen via addEventListener():

pdfReaderRef.current?.addEventListener(CPDFEvent.ANNOTATIONS_CREATED, (annotation) => {
  // annotation is CPDFAnnotation object or its subclass objects
  console.log(JSON.stringify(annotation));
});

Annotation Selected Event

Event name: CPDFEvent.ANNOTATIONS_SELECTED

Triggered when the user selects an annotation:

pdfReaderRef.current?.addEventListener(CPDFEvent.ANNOTATIONS_SELECTED, (annotation) => {
  // annotation is CPDFAnnotation object or its subclass objects
  console.log(JSON.stringify(annotation));
});

Annotation Deselected Event

Event name: CPDFEvent.ANNOTATIONS_DESELECTED

Triggered when the user deselects an annotation:

pdfReaderRef.current?.addEventListener(CPDFEvent.ANNOTATIONS_DESELECTED, (annotation) => {
  // annotation is CPDFAnnotation object or its subclass objects, may be null
  console.log(JSON.stringify(annotation));
});