Guides

Custom Annotation Creation Workflows

These APIs have different effects on the built-in SDK workflow:

Workflow APIs

Goal	API	Effect on default behavior
Observe a completed annotation creation	CPDFEvent.ANNOTATIONS_CREATED	Does not change default behavior.
Replace the Signature, Image, Stamp, Link, or Note creation UI	onAnnotationCreationPrepared	After disabling the corresponding built-in UI, the application must complete or cancel the workflow.
Replace the action for an existing Note or Link	onInterceptAnnotationActionCallback	The SDK no longer performs the default edit or navigation action.
Replace selected form-field actions	onInterceptWidgetActionCallback	The SDK no longer performs the default action for intercepted field types.

Customize Annotation Creation

Annotation type	Configuration to disable	annotation parameter	Next application action
CPDFAnnotationType.SIGNATURE	autoShowSignPicker: false	null	Select an image, then call prepareNextSignature().
CPDFAnnotationType.STAMP	autoShowStampPicker: false	null	Select a stamp, then call prepareNextStamp().
CPDFAnnotationType.PICTURES	autoShowPicPicker: false	null	Select an image, then call prepareNextImage().
CPDFAnnotationType.LINK	autoShowLinkDialog: false	Created CPDFLinkAnnotation	Set action and call _pdfDocument.updateAnnotation(); remove it on cancel.
CPDFAnnotationType.NOTE	autoShowNoteEditDialog: false	Created CPDFNoteAnnotation	Set content and call _pdfDocument.updateAnnotation(); remove it on cancel.

const configuration = ComPDFKit.getDefaultConfig({
  annotationsConfig: {
    autoShowSignPicker: false,
    autoShowStampPicker: false,
    autoShowPicPicker: false,
    autoShowLinkDialog: false,
    autoShowNoteEditDialog: false,
  },
});

Signature, Stamp, and Image annotations have not yet been placed when the callback runs:

await pdfReaderRef.current?.prepareNextSignature(signaturePath);
await pdfReaderRef.current?.prepareNextImage(imagePath);
await pdfReaderRef.current?.prepareNextStamp({
  standardStamp: CPDFStandardStamp.APPROVED,
});

Link and Note objects already exist when the callback runs. Updating the JavaScript object alone does not persist the change; call updateAnnotation() or removeAnnotation(). See Create Annotations for the complete custom Note confirm/cancel workflow.

Intercept Actions on Existing Annotations

Set interceptNoteAction or interceptLinkAction to true in annotationsConfig. The application must then handle Note editing, web links, or page navigation in onInterceptAnnotationActionCallback. Do not enable interception if you only need passive observation.

Intercept Form-Field Actions

List only the required CPDFWidgetType values in formsConfig.interceptFormWidgetActions. After changing the returned CPDFWidget, call pdfReaderRef.current?._pdfDocument.updateWidget(widget). Use interceptAllFormWidgetActions: true only when the application implements every form-field behavior.