--- title: "Z-index for stacking order of PDF annotations on iOS | Nutrient" canonical_url: "https://www.nutrient.io/guides/ios/annotations/annotation-z-index/" md_url: "https://www.nutrient.io/guides/ios/annotations/annotation-z-index.md" last_updated: "2026-06-09T10:32:42.804Z" description: "Learn how the z-index affects annotation stacking order on pages. Discover how to determine and change the z-index of annotations effectively." --- # Z-index for annotation stacking order on iOS The annotation z-index defines the stacking order of annotations on a page. An annotation with a lower z-index will be positioned at the back of the page, whereas annotations with a higher number will be positioned on top of annotations with a lower z-index. This means the annotations with a lower z-index will be obscured if the annotations are overlapping. A z-index of `0` means that the annotation is all the way at the back, while the highest z-index means that the annotation is at the front. By default, when creating and adding new annotations, the new annotations will be added on top of existing annotations. ## Determine the z-index of an annotation The z-index is not a property on an annotation, but it is defined by the index in the annotations array of a page. So, to determine the current z-index of an annotation, you need to fetch all annotations for a page and get the index of the annotation in question in the array. ## Change the z-index of an annotation The z-index is not a property on an annotation, but it is defined by the index in the annotations array of a page. To determine the current z-index of an annotation, you need to get the annotations array for a particular page using [`Document.annotations(at:)`](https://www.nutrient.io/api/ios/documentation/pspdfkit/document/annotations(at:)) and compare the annotations to the annotations in this array. ### User interface The z-index can be changed via the annotation inspector and the annotation list. This UI feature can be disabled by setting [`allowAnnotationZIndexMoves`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/pdfconfiguration/allowannotationzindexmoves) of [`PDFConfiguration`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/pdfconfiguration) to `NO`. #### Annotation list The moving of annotations is also supported by reordering them in the annotation list while in edit mode. This can be disabled via the [`allowAnnotationZIndexMoves`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/annotationtableviewcontroller/allowannotationzindexmoves) property on [`AnnotationTableViewController`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/annotationtableviewcontroller). This property is set to the value of [`PDFConfiguration.allowAnnotationZIndexMoves`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/pdfconfiguration/allowannotationzindexmoves) whenever [`AnnotationTableViewController`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/annotationtableviewcontroller) is presented from within Nutrient.![](@/assets/guides/ios/annotations/z-index/list.png) #### Inspector When an annotation supports changing the z-index (when there are at least two annotations on a page), [`AnnotationStyleViewController`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/annotationstyleviewcontroller) shows an Order entry, where the annotation can be moved to the front, one position forward, one position backward, or to the back.![](@/assets/guides/ios/annotations/z-index/inspector.png) ### Programmatically You can programmatically move annotations by calling [`updateAnnotationsOnPage(at:updates:)`](https://www.nutrient.io/api/ios/documentation/pspdfkit/annotationmanager/updateannotationsonpage(at:updates:)) on [`AnnotationManager`](https://www.nutrient.io/api/ios/documentation/pspdfkit/annotationmanager) and using [`moveAnnotation(atZIndex:toZIndex:)`](https://www.nutrient.io/api/ios/documentation/pspdfkit/annotationupdate/moveannotation(atzindex:tozindex:)) on the [`AnnotationUpdate`](https://www.nutrient.io/api/ios/documentation/pspdfkit/annotationupdate) object provided in the update block. This will move an annotation at the specified z-index to another z-index. To move an annotation all the way to the back (to z-index `0`), you can use the following code snippet: ### SWIFT ```swift let annotation: Annotation = // Annotation to move. guard let annotationManager = document.documentProviderForPage(at: annotation.pageIndex)?.annotationManager else { return } do { try annotationManager.updateAnnotationsOnPage(at: annotation.pageIndex) { updater in if let currentZIndex = updater.annotations.firstIndex(of: annotation) { try updater.moveAnnotation(atZIndex: UInt(currentZIndex), toZIndex: 0) } } } catch (let error) { // handle error } ``` ### OBJECTIVE-C ```objc PSPDFAnnotation *annotation = // Annotation to move. PSPDFAnnotationManager *annotationManager = [document documentProviderForPageAtIndex:annotation.pageIndex].annotationManager; [annotationManager updateAnnotationsOnPageAtIndex:annotation.pageIndex error:nil withUpdateBlock:^(id annotationUpdate, NSError **updateError) { NSUInteger currentZIndex = [annotationUpdate.annotations indexOfObjectIdenticalTo:annotation]; return [annotationUpdate moveAnnotationAtZIndex:currentZIndex toZIndex:0 error:**updateError]; }]; ``` ## Add a new annotation at a specific z-index When adding a new annotation, you can also specify the z-index it should be inserted at. This can be done with the [`insert(_:atZIndex:options:)`](https://www.nutrient.io/api/ios/documentation/pspdfkit/document/insert(_:atzindex:options:)) API on [`Document`](https://www.nutrient.io/api/ios/documentation/pspdfkit/document). ### Considerations Currently, z-index moving is unsupported when using multiple annotation providers. Also bear in mind that when specifying the z-index, either when inserting or when moving annotations, it always needs to be less than the number of annotations that will be on the document page. There are a few annotation types that always float on top of other annotations, since they are not drawn on the PDF page but are overlaid as views, and therefore don’t respect the z-index. These annotations are note, sound, and link annotations. Selected annotations are always rendered on top, so if you change the z-index of the selected annotation via the inspector, the result will not become apparent before deselecting. Some annotation types, like stamps, don’t have any editable properties other than the z-index, so we decided not to show the inspector for these annotations. These annotations must be moved using the annotation list. --- ## Related pages - [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) - [Annotations object model on iOS](/guides/ios/annotations/the-annotation-object-model.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) - [Setting annotation authors on iOS](/guides/ios/annotations/annotation-author-name.md) - [Drag-and-drop annotations on iOS](/guides/ios/annotations/create-edit-and-remove/drag-and-drop.md) - [Detect changes to PDF annotations in iOS apps](/guides/ios/annotations/detecting-if-annotations-have-changed.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) - [Undo and redo annotations on iOS](/guides/ios/features/undo-redo.md)