Annotations

You read and edit annotations through two services: the document service (doc.annotations) for cheap whole-document reads, and the page service (doc.page(pon).annotations) for typed reads and edits. The examples below assume you already opened a document (see Quick start).

Reading annotations#

For a quick “what’s where” overview, the document service has two fast read paths:

// Every page, cheapest read.
const all = await doc.annotations.listRawAll();
 
// A single page, by its page object number.
const onePage = await doc.annotations.listRaw(pageObjectNumber);

To get the full, typed annotations on one page, use the page service:

const page = doc.page(pageObjectNumber);
const { annotations } = await page.annotations.list();

Adding an annotation#

Call create() with the annotation you want. Each kind has its own fields — see Annotation types for the full list. Here’s a highlight:

const page = doc.page(pageObjectNumber);
 
const { created } = await page.annotations.create({
  subtype: 'highlight',
  color: { r: 255, g: 215, b: 0 },
  opacity: 0.4,
  quadPoints: [
    {
      p1: { x: 72, y: 712 },
      p2: { x: 272, y: 712 },
      p3: { x: 72, y: 696 },
      p4: { x: 272, y: 696 },
    },
  ],
});
 
// `created` is the new annotation. Keep `created.ref` to edit it later.

Measurements#

Measurements use the existing annotation types and editing methods. Set the dimension intent and attach a rectilinear measure dictionary:

The pure helpers exported by @embedpdf/engine-core include measureFromKnownLength, measureFromRatio, measurementReadout, and formatMeasurement. A known-length calibration takes a length in PDF user-space units and its real-world value and unit. A ratio calibration also accepts the page’s userUnit. The readout reports the formatted label and numeric value, or an unavailable reason when the imported scale or geometry cannot be interpreted. Polygon readouts also include a formatted perimeter when distance formats exist. A perimeter sums the open polyline’s segments; it does not add a closing segment. Areas require a simple, nonzero boundary. Crossing, overlapping, or degenerate boundaries return invalid-geometry instead of a potentially misleading area.

The engine derives contents on creation and when geometry, measure, intent, or contents is updated. Supplying a different contents string cannot override an available measurement result. A style-only edit preserves the stored label; missing or unsupported scales leave it unchanged. Preview calculations normalize coordinates and conversion factors to the same float precision used by the PDF runtime.

Captions and placement#

Set caption.enabled to paint the saved label into the annotation’s appearance. Imported polygons and polylines keep their existing appearance behavior until explicitly enabled.

• A line caption uses position: 'inline' | 'top' and an optional offset: { along, perpendicular }. These are displacements in PDF units along the directed line and its positive 90-degree normal.
• A polygon or polyline caption uses an optional center: { x, y }. This is an absolute point in PDF user space: y increases upward and the original page origin is retained. The point (0, 0) is a valid manual placement.
• Caption patches merge with saved placement. Hiding a caption retains its position; offset: null or center: null restores automatic placement, and caption: null clears the caption settings.
• A manual shape center follows a verified translation or rotation of all vertices. Editing individual vertices leaves it fixed. An explicit center in the patch takes precedence. The editor also carries the center during group resizing; it writes the resulting absolute PDF point explicitly.
• Automatic area captions use the polygon centroid, with an interior fallback for concave polygons. Perimeter captions sit just above the halfway point of the path. Captions follow the annotation’s authored rotation, including when the label has been placed manually.

Viewer authoring#

The Measure toolbar provides Distance, Perimeter, Area, and Calibrate. Each drawing icon previews that tool’s current stroke color; changing the default updates its toolbar, overflow-menu, and cursor icon together.

Click successive vertices for perimeter or area, then double-click or use the normal drawing completion action to finish. Press Escape to cancel. The scale is captured at the first vertex and stays fixed throughout that drawing. An invalid area previews an unavailable value and cannot be finished.

Select a measurement and drag its text to reposition the label. Labels have no separate visible handle. The selection frame encloses the shape and label, and rotation uses that frame’s center. Edited measurements stay vector-rendered, following the same lifecycle as other annotations.

The measurement sidebar shows both area and perimeter for a selected area. Its Area unit control changes the area display independently of distance formatting; Reset label position returns selected shape labels to automatic placement. The measurement capability exposes areaUnits() and setAreaUnit() alongside its existing unit, precision, and calibration methods.

Page calibration#

Both local and cloud engines expose page.measure. Its viewports() method returns the page’s measurement regions in drawing order; viewportForPoint selects the last containing region, including regions with unsupported measures. The owned flag identifies EmbedPDF’s calibration viewport.

setScale(measure) saves a full-page calibration, while setScale(null) removes it. Other producers’ viewports survive both operations. Calibration emits page.viewportsChanged, persists with the document or layer, and leaves existing annotations’ scale snapshots unchanged. To recalibrate an existing annotation, update its measure explicitly.

Reading viewports requires doc.open; changing calibration requires doc.annotate.modify. Foreign measures such as /GEO remain readable and are preserved in the PDF, but cannot be authored through the measurement API.

Updating and deleting#

You never build an identity by hand. Every annotation you read or create comes with a ref — pass that same ref back to update, delete, or move:

const { annotations } = await page.annotations.list();
const note = annotations[0];
 
// Change something. Repeat the `subtype` so the engine knows which fields are valid.
await page.annotations.update(note.ref, { subtype: note.subtype, contents: 'edited note' });
 
// Remove it.
await page.annotations.delete(note.ref);

Reordering#

move() changes annotation order on a page. Pass the annotations to move (a contiguous block; a single ref is the common case) and the position to insert them at:

await page.annotations.move([note.ref], 0); // move to the front

Styling#

Most annotations share the same styling fields.

Color is RGB only — { r, g, b }, each 0–255. Transparency is a separate opacity field (0–1), not part of the color:

await page.annotations.update(note.ref, {
  subtype: note.subtype,
  color: { r: 0, g: 120, b: 255 },
  opacity: 0.6,
});

When you omit a styling field, the engine uses a sensible default: a 1pt solid red stroke at full opacity.

Flags#

Every annotation has the standard PDF flags. Set only the ones you care about — the rest keep their current value:

// On create: print, but don't show on screen.
await page.annotations.create({
  subtype: 'square',
  rect: { left: 100, bottom: 600, right: 200, top: 680 },
  color: { r: 0, g: 0, b: 0 },
  flags: { print: true, noView: true },
});
 
// Later: lock from editing without touching any other flag.
await page.annotations.update(note.ref, { subtype: note.subtype, flags: { readOnly: true } });

Available flags: invisible, hidden, print, noZoom, noRotate, noView, readOnly, locked, toggleNoView, lockedContents.

Rendering annotations#

Every annotation carries its visual as an appearance stream inside the PDF. To display them, batch-render a page’s appearances into images:

const { appearances } = await page.annotations.renderAppearanceImages({ scale: 2 });
 
for (const ap of appearances) {
  // ap.ref   — which annotation this is
  // ap.rect  — WHERE to place it (PDF points, y-up)
  // ap.image — a lazy image handle; ap.image.objectUrl() gives you a blob: URL
}

One convention to know: when an annotation’s DTO carries both rotation and unrotatedRect (the box-family kinds — square, circle, free text, stamp), its appearance renders rotation-stripped: ap.rect is the logical unrotatedRect and the image is the flat content mapped into it. You re-apply that rotation as a transform about the box centre. Everything else — line, polyline, polygon, ink (their rotation is pre-baked into the geometry) and annotations from other tools — comes back as-is, placed by ap.rect, no transform needed.

const { url } = await ap.image.objectUrl();
// `annotation` is the matching entry from list() — ref, rotation, etc.
const stripped = 'unrotatedRect' in annotation && annotation.unrotatedRect && annotation.rotation;
<img
  src={url}
  style={{
    position: 'absolute',
    /* place by ap.rect, converted to your view coordinates */
    transform: stripped ? `rotate(${annotation.rotation}deg)` : undefined,
    transformOrigin: 'center',
  }}
/>;

This split is what makes interactions cheap:

• Rotating an annotation never needs a re-render — the image is rotation-invariant; only your transform changes.
• Moving never needs a re-render — only the placement changes.
• Resizing can stretch the existing image live during the gesture, then fetch once after committing the new rect (the engine re-fits the appearance natively).

Re-render appearances when the content changed — a committed geometry edit, a style patch, a replaced stamp source — or when your zoom level changes and you want a sharper raster (scale).

Flattening chosen annotations#

pages.flatten bakes every annotation of a page into its content. The per-page annotation service does the same for a chosen set, and reports what happened to each:

const result = await page.annotations.flatten!([refA, refB], 'display');
result.results; // [{ ref: refA, status: 'applied' }, { ref: refB, status: 'skipped' }]

applied annotations are painted into the page and removed; skipped ones stay where they were — hidden for the usage ('display' or 'print'), a Popup, or without a usable normal appearance — so a caller can say “2 of 3 flattened”. A ref on another page rejects the whole call before anything is mutated. Gated like pages.flatten: doc.pages.modify and doc.annotate.modify.

Exporting appearances as a PDF#

The same plan aimed at a fresh page: the normal appearances of the given annotations, flattened into a new single-page PDF sized to their union rect — vector, positions preserved, exactly as this page shows them. The source document is untouched.

const bytes = await page.annotations.exportAppearance!([refA, refB]);
// …a one-page PDF: hand it to a stamp library, or download it.

All-or-nothing: any ref that is not on the page, hidden, or without an appearance rejects the call with InvalidArg. A derived read that egresses content, so it is gated by doc.download like pages.extract.

Edit sessions (cloud)#

On the cloud, structural edits addressed by index (a delete or move that shifts the array) need an active edit session. It proves you’re the only one editing those pages — a guard against two clients shifting the same page at once.

const session = await doc.annotations.beginWeakEdit([pageObjectNumber]);
 
try {
  // …index-addressed structural edits on covered pages…
  await session.heartbeat(); // keep the session alive
} finally {
  await session.release();
}

Next#