Redactions from text selection

The instance.annotations.redaction.createFromCurrentTextSelection() method creates redaction annotations directly from the user’s text selection with no menu, no popover, and no built-in chrome. Pair it with the existing createRedactionsBySearch and applyRedactions APIs to build a redaction workflow entirely from your own UI.

When to use this

Reach for selection-driven redactions when you’re building:

• A custom inline button that appears on text selection and converts the selection to a redaction in a single click.
• A bulk-redaction workflow that combines selection-driven redactions with pattern-driven ones.
• A custom confirmation flow that previews the redaction before applying it permanently.
• A keyboard shortcut your application defines for “redact this selection.”

API reference

Because createFromCurrentTextSelection() throws when there’s no selection, gate the call on an active text selection before invoking it.

Example: A custom inline redaction button

This example wires a host-app button to convert the user’s text selection into a redaction. A second button applies all pending redactions when the user is ready:

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

const toolbar = document.getElementById("redaction-toolbar");
const redactButton = toolbar.querySelector("#redact-selection");
const applyButton = toolbar.querySelector("#apply-redactions");

instance.addEventListener("textSelection.change", (selection) => {
  // The event emits either a `TextSelection` or `null`. A null check is enough.
  redactButton.disabled = !selection;
});

redactButton.onclick = () => {
  const created = instance.annotations.redaction.createFromCurrentTextSelection();
  console.log(`Created ${created.size} redaction(s).`);
};

applyButton.onclick = async () => {
  const confirmed = window.confirm(
    "Applying redactions removes the underlying content permanently. Continue?"
  );
  if (confirmed) {
    await instance.applyRedactions();
  }
};

The created redactions are pending, and they appear as dark overlays on the page, but the underlying content isn’t removed until applyRedactions() runs. This gives the user a chance to review what’s been marked for redaction before it becomes permanent.

Example: Combine selection and pattern redactions

The selection-driven and pattern-driven flows compose naturally, and you can create both kinds of redactions in the same workflow before applying them:

async function redactSensitiveData(instance) {
  if (instance.getTextSelection()) {
    instance.annotations.redaction.createFromCurrentTextSelection();
  }
  await instance.createRedactionsBySearch(/\d{3}-\d{2}-\d{4}/);
  await instance.createRedactionsBySearch("CONFIDENTIAL");
}

After the function runs, the document has redactions for the user’s manually selected text, plus every Social Security Number pattern and every literal CONFIDENTIAL mention. Call applyRedactions() once to commit them all together.

Choosing between the selection and pattern paths

Both APIs create the same kind of redaction annotation. Use the one that matches the workflow.

Related

• Color presets — The cross-namespace pattern for reading preset colors.
• Redaction guide — The broader redaction feature reference.