Programmatically create annotations in React Native

Nutrient React Native SDK offers APIs to manipulate annotations programmatically. All of these functions use the Instant JSON format to represent annotations.

FunctionDescription
getAnnotations(type)Get all annotations of the given type. See the list of all supported annotation types.
getAnnotationsForPage(pageIndex, type)Get all annotations on the given page index of the given type. See the list of all supported annotation types.
getAllUnsavedAnnotations()Get all the unsaved annotations from the entire document in Instant JSON format.
addAnnotations([jsonAnnotations])Add the given annotations to the document.
applyInstantJSON(documentJSON)Apply the given document JSON to the document.
updateAnnotations([jsonAnnotations])Update the given annotations in the document. Only modified properties will be reapplied.
removeAnnotations([jsonAnnotations])Remove the given annotations from the document. If the given annotations don’t exist, this method does nothing.

Getting all annotations

The example below shows how to get all annotations on the first page of a document:

// Get all ink annotations on the first page of the document.
const allInkAnnotations = await this.pdfRef.current?.getDocument().getAnnotationsForPage(0, Annotation.Type.INK);


// Get all annotations on the entire document.
const allAnnotations = await this.pdfRef.current?.getDocument().getAnnotations();

Removing all annotations

The example below shows how to remove an existing ink annotation from the first page of a document:

// Get all ink annotations on the first page of the document.
const inkAnnotations = this.pdfRef.current?.getDocument()
  .getAnnotationsForPage(0, Annotation.Type.INK);


// Get the first ink annotation.
const firstInkAnnotation = inkAnnotations[0];


// Remove the first ink annotation.
this.pdfRef.current?.getDocument()
  .removeAnnotations([firstInkAnnotation]);

Adding annotations

The example below shows how to add an ink annotation programmatically by creating an InkAnnotation object and using the addAnnotations API:

const inkAnnotation: InkAnnotation = new InkAnnotation({
    type: 'pspdfkit/ink',
    bbox: [89.586334228515625, 98.5791015625, 143.12948608398438, 207.1583251953125],
    pageIndex: 0,
    isDrawnNaturally: false,
    lines: {
      intensities: [
        [0.5, 0.5, 0.5],
        [0.5, 0.5, 0.5],
      ],
      points: [
        [
          [92.086334228515625, 101.07916259765625],
          [92.086334228515625, 202.15826416015625],
          [138.12950134277344, 303.2374267578125],
        ],
        [
          [184.17266845703125, 101.07916259765625],
          [184.17266845703125, 202.15826416015625],
          [230.2158203125, 303.2374267578125],
        ],
      ],
    }
  });


// Add the ink annotation.
await this.pdfRef.current?.getDocument()
  .addAnnotations([inkAnnotation]);

The following example shows how to add an image annotation programmatically. Because it includes an attachment, you need to create a DocumentJSON object and use the applyInstantJSON API:

const documentJSON: DocumentJSON = {
  "annotations": [
    {
      "bbox": [
        229,
        426,
        125,
        125
      ],
      "contentType": "image/png",
      "createdAt": "2023-08-30T17:15:13Z",
      "creatorName": "Test User",
      "description": "Test",
      "id": "455f261c88f94294a05ebeb494c96cb9",
      "imageAttachmentId": "492adff9842bff7dcb81a20950870be8a0bb665c8d48175680c1e5e1070243ff",
      "name": "my-custom-image-annotation",
      "opacity": 1,
      "pageIndex": 0,
      "rotation": 0,
      "subject": "Test",
      "type": "pspdfkit/image",
      "updatedAt": "2024-05-07T17:15:13Z",
      "v": 2
    }
  ],
  "format": "https://pspdfkit.com/instant-json/v1",
  "attachments": {
    "492adff9842bff7dcb81a20950870be8a0bb665c8d48175680c1e5e1070243ff": {
      "binary": "base64-image-data",
      "contentType": "image/png"
    }
  },
};


// Add the image annotation.
await this.pdfRef.current?.getDocument()
  .applyInstantJSON(documentJSON);

Updating annotations

The example below shows how to update an existing ink annotation from the first page of a document:

// Get all ink annotations on the first page of the document.
const inkAnnotations = this.pdfRef.current?.getDocument()
  .getAnnotationsForPage(0, Annotation.Type.INK);


// Annotation UUID or name can be used to identify the specific annotation to update.
// Ensure the annotation is an `InkAnnotation` in order to cast it.
if (inkAnnotations[0] instanceof InkAnnotation) {
    const inkAnnotation = annotations[0] as InkAnnotation;


    // Update annotation color property.
    inkAnnotation.color = '#FFFFFF';


    await this.pdfRef.current?.getDocument().updateAnnotations([inkAnnotation])
      .catch((error: any) => {
    console.log('Failed to update annotations: ' + JSON.stringify(error));
      });
}

For more details and sample code, see the ProgrammaticAnnotations.tsx example(opens in a new tab) from the Catalog example project.