ReferenceAnnotationRenderingOrderComparator

Type Alias AnnotationRenderingOrderComparator

A comparator function that defines a strict total order for annotation rendering.

Return -1 if a should render below (behind) b, or 1 if a should render above (in front of) b. A strict total order is required — every pair of distinct annotations must have a deterministic ordering.

When set via NutrientViewer.Instance#setAnnotationRenderingOrderComparator, this comparator replaces the SDK's default type-based rendering order for non-interactive annotations (e.g. text markups, ink, images, shapes, stamps).

Interactive annotations — widget annotations (form fields), link annotations, and signature annotations — are always rendered above all other annotations regardless of the comparator. This is required to preserve keyboard tab order and accessibility. Use NutrientViewer.Instance#setPageTabOrder to customize the tab order of interactive annotations.

Limitations:

This only affects the visual stacking order of non-interactive annotations.
Widget, link, and signature annotations always render on top, independent of this comparator, to preserve keyboard accessibility.
It does not change the keyboard tab order. Use NutrientViewer.Instance#setPageTabOrder to customize that separately.
Hit testing (click/tap) follows the DOM stacking context, which matches the visual rendering order set by this comparator — the topmost (last-rendered) annotation receives pointer events first.
It does not affect annotation order in exported PDFs or backend storage. The ordering is purely a local, view-layer concern.

Type Alias

Type Signature

type AnnotationRenderingOrderComparator = (a: AnnotationsUnion, b: AnnotationsUnion) => -1 | 1

Example

// Render image annotations behind everything else, tiebreak by creation time then id.
instance.setAnnotationRenderingOrderComparator((a, b) => {
  const isImageA = a instanceof NutrientViewer.Annotations.ImageAnnotation;
  const isImageB = b instanceof NutrientViewer.Annotations.ImageAnnotation;
  if (isImageA !== isImageB) return isImageA ? -1 : 1;
  if (a.createdAt < b.createdAt) return -1;
  if (a.createdAt > b.createdAt) return 1;
  return a.id < b.id ? -1 : 1;
});

Type Declaration

Parameters

aAnnotationsUnion

The first annotation.

bAnnotationsUnion

The second annotation.

Returns

-1 | 1

-1 if a renders below b, 1 if a renders above b.