Headless ink annotations

The instance.annotations.ink namespace exposes the live drawing state the SDK tracks while the user is drawing an ink annotation. Combine it with the existing ink configuration and event surfaces to build an ink experience that doesn’t go through the default toolbar.

When to use this

Reach for the headless ink API when you’re building:

• A floating brush toolbar that lives outside the viewer and stays visible across documents.
• A status indicator that reflects whether the user is currently in the middle of a stroke.
• An analytics or collaboration layer that tracks how long users spend drawing.
• Switching the eraser between point and stroke modes, either at load time or at runtime from a custom toolbar.

API reference

The headless ink surface splits into two parts: the live drawing state you can read while a stroke is in progress, and the eraser mode configuration.

Drawing state

getDrawingState() returns an object with:

• isDrawing: boolean — Whether the user is currently in the middle of a stroke.
• activeAnnotationId: string | null — The ID of the ink annotation being drawn, or null when idle.
• lastDrawStartAt: number | null — Timestamp (ms since epoch) when the most recent stroke started.
• lastDrawEndAt: number | null — Timestamp when the most recent stroke ended.
• lastDrawDurationMs: number | null — Duration of the most recent stroke in milliseconds.

The state is transient telemetry; it doesn’t include the stroke geometry, color, or width. For brush settings, refer to the inkAnnotation annotation preset. For the rendered stroke geometry, read the annotation directly once it has been created.

Eraser configuration

Events

Example: A status indicator wired to drawing state

This example renders an indicator outside the viewer container that flips when the user starts or stops drawing:

const instance = await NutrientViewer.load({
  container: "#viewer",
  document: "contract.pdf"
});

const indicator = document.getElementById("drawing-indicator");

function render() {
  const state = instance.annotations.ink.getDrawingState();
  indicator.classList.toggle("is-active", state.isDrawing);
  indicator.textContent = state.isDrawing
    ? "Drawing…"
    : state.lastDrawDurationMs != null
      ? `Last stroke: ${Math.round(state.lastDrawDurationMs)}ms`
      : "Idle";
}

instance.addEventListener("ink.drawing", render);
render();

You can also poll getDrawingState() synchronously from a render loop — for example, when you want to step the indicator at a fixed frame rate:

function frame() {
  const state = instance.annotations.ink.getDrawingState();
  indicator.classList.toggle("is-active", state.isDrawing);
  requestAnimationFrame(frame);
}

requestAnimationFrame(frame);

Example: Configure the eraser

Set the initial eraser mode by passing inkEraserMode to NutrientViewer.load():

const instance = await NutrientViewer.load({
  container: "#viewer",
  document: "contract.pdf",
  inkEraserMode: NutrientViewer.InkEraserMode.STROKE
});

InkEraserMode.POINT (the default) erases individual points as the eraser passes over them. InkEraserMode.STROKE erases the entire stroke under the eraser as a single action.

Switch the mode at runtime by calling setEraserMode(), which is typically wired up to a custom toolbar control:

document.getElementById("eraser-mode-stroke").onclick = () => {
  instance.annotations.ink.setEraserMode(NutrientViewer.InkEraserMode.STROKE);
};

document.getElementById("eraser-mode-point").onclick = () => {
  instance.annotations.ink.setEraserMode(NutrientViewer.InkEraserMode.POINT);
};

Related

• Color presets — The cross-namespace pattern for reading preset colors from inside a custom UI.
• Ink annotation reference — The full InkAnnotation API.