---
title: "Annotations object model on iOS | Nutrient SDK"
canonical_url: "https://www.nutrient.io/guides/ios/annotations/the-annotation-object-model/"
md_url: "https://www.nutrient.io/guides/ios/annotations/the-annotation-object-model.md"
last_updated: "2026-05-25T12:14:42.920Z"
description: "This article explains how the Annotation and FormElement classes can be used. For an overview of annotation support in Nutrient."
---

# Annotations object model on iOS

This article explains how the [`Annotation`](https://www.nutrient.io/api/ios/documentation/pspdfkit/annotation) and [`FormElement`](https://www.nutrient.io/api/ios/documentation/pspdfkit/formelement) classes can be used. For an overview of annotation support in Nutrient, see the [introduction to annotations](https://www.nutrient.io/../../annotations/introduction-to-annotations) guide.

To learn more about how you can check if annotations have been added/removed/changed, see the [detecting if annotations have changed](https://www.nutrient.io/../../annotations/detecting-if-annotations-have-changed) guide.

## Changing annotations

The annotation object model is based on [`ModelObject`](https://www.nutrient.io/api/ios/documentation/pspdfkit/modelobject). Changes need to be made on the main thread. If a [`PDFViewController`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/pdfviewcontroller) is currently displaying the [`Document`](https://www.nutrient.io/api/ios/documentation/pspdfkit/document) that owns the annotation, you should emit a change notification to ensure the UI is correctly updated:

### SWIFT

```swift

let freeTextAnnotation: FreeTextAnnotation =..
freeTextAnnotation.contents = "These are my new note contents."

NotificationCenter.default.post(name: NSNotification.Name.PSPDFAnnotationChanged, object: freeTextAnnotation, userInfo: [PSPDFAnnotationChangedNotificationKeyPathKey: ["contents"]])

```

### OBJECTIVE-C

```objc

PSPDFFreeTextAnnotation *freeTextAnnotation =...;
freeTextAnnotation.contents = @"These are my new note contents.";

[NSNotificationCenter.defaultCenter postNotificationName:PSPDFAnnotationChangedNotification
object:freeTextAnnotation userInfo:@{PSPDFAnnotationChangedNotificationKeyPathKey : @[@"contents"]}];

```

This sends a [`PSPDFAnnotationChangedNotification`](https://www.nutrient.io/api/ios/documentation/pspdfkit/foundation/nsnotification/name/pspdfannotationchanged). The [`PSPDFAnnotationChangedNotificationKeyPathKey`](https://www.nutrient.io/api/ios/documentation/pspdfkit/pspdfannotationchangednotificationkeypathkey) should match the change you’ve made, as this enables Nutrient to perform additional performance optimizations (for example, various properties might not require a new render step).

## Adding annotations

Annotations can be added by calling [`add(annotations:options:)`](https://www.nutrient.io/api/ios/documentation/pspdfkit/document/add(annotations:options:)) on your [`Document`](https://www.nutrient.io/api/ios/documentation/pspdfkit/document). This will emit a [`PSPDFAnnotationsAddedNotification`](https://www.nutrient.io/api/ios/documentation/pspdfkit/foundation/nsnotification/name/pspdfannotationsadded).

## Deleting annotations

Deleting annotations should be performed by calling [`remove(annotations:options:)`](https://www.nutrient.io/api/ios/documentation/pspdfkit/document/remove(annotations:options:)) on your [`Document`](https://www.nutrient.io/api/ios/documentation/pspdfkit/document). This will emit either [`PSPDFAnnotationsRemovedNotification`](https://www.nutrient.io/api/ios/documentation/pspdfkit/foundation/nsnotification/name/pspdfannotationsremoved) or [`PSPDFAnnotationChangedNotification`](https://www.nutrient.io/api/ios/documentation/pspdfkit/foundation/nsnotification/name/pspdfannotationchanged), depending on whether or not the annotation has already been saved in the PDF. If it has been saved, we need to use soft delete to track and correctly update the file.

## Thread safety

Annotations should only be accessed on the main thread. They can be created and configured on any thread, but as soon as they’re added to a [`Document`](https://www.nutrient.io/api/ios/documentation/pspdfkit/document), they may only be modified on the main thread. Violating this convention can lead to crashes, data corruption, and deadlock.

You can also access annotations when tapping on them by implementing [`PDFViewControllerDelegate`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/pdfviewcontrollerdelegate) methods like [`pdfViewController(_:didTapOn:annotationPoint:annotationView:pageView:viewPoint:)`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/pdfviewcontrollerdelegate/pdfviewcontroller(_:didtapon:annotationpoint:annotationview:pageview:viewpoint:)).
---

## Related pages

- [Setting annotation authors on iOS](/guides/ios/annotations/annotation-author-name.md)
- [Define annotation behavior with flags on iOS](/guides/ios/annotations/annotation-flags.md)
- [How to embed files in PDF annotations on iOS](/guides/ios/annotations/create-edit-and-remove/attach-a-file.md)
- [Detect changes to PDF annotations in iOS apps](/guides/ios/annotations/detecting-if-annotations-have-changed.md)
- [Drag-and-drop annotations on iOS](/guides/ios/annotations/create-edit-and-remove/drag-and-drop.md)
- [Defining annotation blend modes on iOS](/guides/ios/annotations/annotation-blend-modes.md)
- [Disable PDF annotation editing for iOS users](/guides/ios/annotations/create-edit-and-remove/disable-editing.md)
- [Image picker: Add image annotations to PDFs on iOS](/guides/ios/miscellaneous/image-picker.md)
- [Annotation state manager on iOS](/guides/ios/annotations/annotation-state-manager.md)
- [Programmatically create PDF annotations on iOS](/guides/ios/annotations/programmatically-creating-annotations.md)
- [Z-index for annotation stacking order on iOS](/guides/ios/annotations/annotation-z-index.md)
- [Undo and redo annotations on iOS](/guides/ios/features/undo-redo.md)