Redaction Plugin

The Redaction Plugin provides the tools to permanently remove sensitive content from a PDF document. Unlike annotations which are simply layered on top, redaction is a destructive process that alters the underlying PDF content, making it unrecoverable.

The process involves two main stages:

Marking: Users mark content for redaction by selecting text or drawing a rectangle over an area. These marks are called “pending redactions.”
Committing: Users apply the pending redactions, which permanently removes the marked content from the document in the viewer’s memory and, optionally, draws black boxes in its place.

⚠️

Redaction is an irreversible process. Once committed, the original content is removed and cannot be restored from the document.

Operating Modes

The Redaction Plugin supports two operating modes:

Mode	Description
Legacy Mode	Pending redactions are stored in internal state. Simple setup, suitable for single-session workflows where one user marks and applies redactions immediately.
Annotation Mode	Pending redactions are stored as PDF REDACT annotations. Enables collaborative workflows, customizable colors, and undo/redo support.

Choose the mode that best fits your use case before implementing.

Installation

The plugin has optional but highly recommended dependencies on the Selection and Interaction Manager plugins, which are required for marking text and areas, respectively.


npm install @embedpdf/plugin-redaction @embedpdf/plugin-selection @embedpdf/plugin-interaction-manager


pnpm add @embedpdf/plugin-redaction @embedpdf/plugin-selection @embedpdf/plugin-interaction-manager


yarn add @embedpdf/plugin-redaction @embedpdf/plugin-selection @embedpdf/plugin-interaction-manager


bun add @embedpdf/plugin-redaction @embedpdf/plugin-selection @embedpdf/plugin-interaction-manager

Registration

Import RedactionPluginPackage and its dependencies, then add them to the plugins array. The dependencies should be registered first.


import { createPluginRegistration } from '@embedpdf/core'
// ... other imports
import { InteractionManagerPluginPackage } from '@embedpdf/plugin-interaction-manager/svelte'
import { SelectionPluginPackage } from '@embedpdf/plugin-selection/svelte'
import { RedactionPluginPackage } from '@embedpdf/plugin-redaction/svelte'
 
const plugins = [
  // ... other essential plugins
  createPluginRegistration(DocumentManagerPluginPackage, { /* ... */ }),
  createPluginRegistration(RenderPluginPackage),
 
  // Register dependencies first
  createPluginRegistration(InteractionManagerPluginPackage),
  createPluginRegistration(SelectionPluginPackage),
 
  // Register and configure the redaction plugin
  createPluginRegistration(RedactionPluginPackage, {
    drawBlackBoxes: true, // Draw black boxes over redacted content
  }),
]

Usage

The plugin’s functionality is primarily managed through the <RedactionLayer /> component and the useRedaction store.

1. Add the `<RedactionLayer />`

This component is responsible for rendering all redaction-related UI, including the text selection highlights, area selection marquee, and all pending redaction marks. It must be placed inside your <Scroller />’s renderPage snippet and be a child of the <PagePointerProvider>.


<script lang="ts">
import { PagePointerProvider } from '@embedpdf/plugin-interaction-manager/svelte';
import { RedactionLayer } from '@embedpdf/plugin-redaction/svelte';
 
let { documentId }: { documentId: string } = $props();
</script>
 
{#snippet renderPage(page)}
  <PagePointerProvider {documentId} pageIndex={page.pageIndex}>
    <RenderLayer {documentId} pageIndex={page.pageIndex} />
    <SelectionLayer {documentId} pageIndex={page.pageIndex} />
    <RedactionLayer {documentId} pageIndex={page.pageIndex} />
  </PagePointerProvider>
{/snippet}
 
<Scroller {documentId} {renderPage} />

The useRedaction store provides the state of the redaction process (e.g., how many marks are pending) and a provides object with methods to control it for a specific document. You can build a toolbar to allow users to switch between redaction modes and apply their changes.


<script lang="ts">
import { useRedaction } from '@embedpdf/plugin-redaction/svelte';
 
let { documentId }: { documentId: string } = $props();
const redaction = useRedaction(() => documentId);
</script>
 
{#if redaction.provides}
  <div>
    <button onclick={() => redaction.provides?.toggleRedactSelection()}>Mark Text</button>
    <button onclick={() => redaction.provides?.toggleMarqueeRedact()}>Mark Area</button>
    <span>{redaction.state.pendingCount} pending marks</span>
    <button
      onclick={() => redaction.provides?.commitAllPending()}
      disabled={redaction.state.pendingCount === 0}
    >
      Apply All Redactions
    </button>
  </div>
{/if}

You can provide a selectionMenu snippet to the <RedactionLayer /> to display a custom UI when a user clicks on a pending redaction mark. This is useful for allowing users to apply or remove individual marks.


<script lang="ts">
import { RedactionLayer, useRedaction } from '@embedpdf/plugin-redaction/svelte';
 
let { documentId }: { documentId: string } = $props();
const redaction = useRedaction(() => documentId);
</script>
 
<RedactionLayer {documentId} pageIndex={page.pageIndex}>
  {#snippet selectionMenuSnippet({ selected, context, menuWrapperProps, rect })}
    {#if selected}
      <span style={menuWrapperProps.style} use:menuWrapperProps.action>
        <div
          style:position="absolute"
          style:top="{rect.size.height + 10}px"
          style:left="0"
          style:pointer-events="auto"
        >
          <button onclick={() => redaction.provides?.removePending(context.item.page, context.item.id)}>Remove</button>
        </div>
      </span>
    {/if}
  {/snippet}
</RedactionLayer>

Live Example

This example demonstrates the full redaction workflow in legacy mode. Use the “Mark Text” button to select text, or “Mark Area” to draw rectangles. Click on a pending mark to see the contextual menu, then apply or remove individual marks. Use “Apply All” to permanently redact all pending marks.

Annotation Mode

The Redaction Plugin supports an alternative annotation mode where pending redactions are stored as PDF REDACT annotations instead of internal state. This integrates with the Annotation Plugin and provides:

Customizable colors: Change the mark and overlay colors for each redaction
Collaborative workflows: One user can prepare redactions, save the PDF, and send it to another user for review. The reviewer can inspect, modify, or apply the redactions
Undo/redo support: Integrates with the History Plugin for full undo/redo functionality
Persistent state: Redaction marks are saved as part of the PDF and persist across sessions

ℹ️

Use annotation mode when you need collaborative review workflows, customizable colors, or want redaction marks to be saved into the PDF for later review.

Enabling Annotation Mode

To enable annotation mode, register AnnotationPluginPackage and set useAnnotationMode: true:


import { createPluginRegistration } from '@embedpdf/core'
import { InteractionManagerPluginPackage } from '@embedpdf/plugin-interaction-manager/svelte'
import { SelectionPluginPackage } from '@embedpdf/plugin-selection/svelte'
import { AnnotationPluginPackage } from '@embedpdf/plugin-annotation/svelte'
import { RedactionPluginPackage } from '@embedpdf/plugin-redaction/svelte'
import { HistoryPluginPackage } from '@embedpdf/plugin-history/svelte'
 
const plugins = [
  // ... other essential plugins
  createPluginRegistration(DocumentManagerPluginPackage, { /* ... */ }),
  createPluginRegistration(RenderPluginPackage),
  createPluginRegistration(InteractionManagerPluginPackage),
  createPluginRegistration(SelectionPluginPackage),
  createPluginRegistration(HistoryPluginPackage),
  createPluginRegistration(AnnotationPluginPackage),
  createPluginRegistration(RedactionPluginPackage, {
    useAnnotationMode: true,
  }),
]

Required Layers

In annotation mode, you need both the AnnotationLayer and RedactionLayer:

AnnotationLayer: Renders the REDACT annotations (pending redactions)
RedactionLayer: Renders the marquee drawing UI and text selection highlights during marking


<script lang="ts">
import { AnnotationLayer } from '@embedpdf/plugin-annotation/svelte';
import { RedactionLayer } from '@embedpdf/plugin-redaction/svelte';
 
let { documentId }: { documentId: string } = $props();
</script>
 
{#snippet renderPage(page)}
  <PagePointerProvider {documentId} pageIndex={page.pageIndex}>
    <RenderLayer {documentId} pageIndex={page.pageIndex} />
    <SelectionLayer {documentId} pageIndex={page.pageIndex} />
    <!-- AnnotationLayer renders REDACT annotations -->
    <AnnotationLayer {documentId} pageIndex={page.pageIndex} />
    <!-- RedactionLayer renders marquee/selection UI during marking -->
    <RedactionLayer {documentId} pageIndex={page.pageIndex} />
  </PagePointerProvider>
{/snippet}
 
<Scroller {documentId} {renderPage} />

Unified Redact Mode

Use toggleRedact() for a unified mode that supports both text selection and area marquee in a single mode:


<script lang="ts">
import { useRedaction, RedactionMode } from '@embedpdf/plugin-redaction/svelte';
 
let { documentId }: { documentId: string } = $props();
const redaction = useRedaction(() => documentId);
 
// Check if redact mode is active
const isActive = $derived(redaction.state.activeType === RedactionMode.Redact);
</script>
 
<!-- Toggle unified redact mode (supports both text and area) -->
<button onclick={() => redaction.provides?.toggleRedact()}>
  Redact
</button>

This unified mode works in both legacy and annotation modes.

Customizing Colors

In annotation mode, redaction colors can be customized. Use the useAnnotation store to access the annotation state and update colors on selected annotations:


<script lang="ts">
import { useAnnotation } from '@embedpdf/plugin-annotation/svelte';
import { PdfAnnotationSubtype, type PdfRedactAnnoObject } from '@embedpdf/models';
 
let { documentId }: { documentId: string } = $props();
const annotation = useAnnotation(() => documentId);
 
// Get the selected REDACT annotation
const selectedRedact = $derived(() => {
  if (!annotation.state.selectedUid) return null;
  const tracked = annotation.state.byUid[annotation.state.selectedUid];
  if (!tracked || tracked.object.type !== PdfAnnotationSubtype.REDACT) return null;
  return tracked.object as PdfRedactAnnoObject;
});
 
// Update colors on the selected annotation
const changeColor = (color: string) => {
  const selected = selectedRedact();
  if (!selected || !annotation.provides) return;
  annotation.provides.updateAnnotation(selected.pageIndex, selected.id, {
    strokeColor: color,
    color: color,
  });
};
</script>

API Reference

Configuration (`RedactionPluginConfig`)

Option	Type	Default	Description
`drawBlackBoxes`	`boolean`	`true`	If `true`, a black rectangle is drawn over the redacted content after committing. Only applies in legacy mode. In annotation mode, the overlay color is controlled by the annotation’s `color` property.
`useAnnotationMode`	`boolean`	`false`	When `true`, pending redactions are stored as PDF REDACT annotations (requires `AnnotationPluginPackage`). When `false`, uses internal pending state (legacy mode).

Component: `<RedactionLayer />`

Renders all UI related to marking and managing redactions.

Prop	Type	Description
`documentId`	`string`	(Required) The ID of the document.
`pageIndex`	`number`	(Required) The page index this layer corresponds to.
`selectionMenu`	`Snippet`	(Optional) A snippet to render a contextual menu when a pending redaction is selected.

Snippet: `selectionMenu`

Prop	Type	Description
`context`	`object`	The context containing the `item` (the pending redaction).
`selected`	`boolean`	`true` if a pending redaction is currently selected.
`menuWrapperProps`	`MenuWrapperProps`	An object containing `style: string` for positioning and `action: Action` to attach to your wrapper element via `use:menuWrapperProps.action`.
`rect`	`Rect`	The bounding box of the selected pending redaction.

Store: `useRedaction(documentId)`

Connects your components to the redaction plugin’s state and methods for a specific document.

Parameters

Parameter	Type	Description
`documentId`	`() => string`	A getter function that returns the document ID to track.

Returns

Property	Type	Description
`state`	`RedactionState`	An object containing the current state of the redaction process.
`provides`	`RedactionScope \| null`	An object with methods to control the plugin, or `null` if not ready.

`RedactionState` Properties

Property	Type	Description
`isRedacting`	`boolean`	`true` when any redaction mode is active.
`activeType`	`RedactionMode \| null`	The currently active mode: `'redact'` (unified), `'redactSelection'` (text only), or `'marqueeRedact'` (area only).
`pending`	`object`	A map of pending redactions, keyed by page number.
`pendingCount`	`number`	The total number of pending redactions across all pages.
`selected`	`object \| null`	The currently selected pending redaction, if any.

`RedactionScope` Methods

A selection of key methods available on the provides object:

Method	Description
`toggleRedact()`	Toggles the unified redact mode (supports both text selection and area marquee).
`enableRedact()`	Enables the unified redact mode.
`isRedactActive()`	Returns `true` if the unified redact mode is active.
`toggleRedactSelection()`	Toggles the text-only redaction mode.
`toggleMarqueeRedact()`	Toggles the area-only redaction mode.
`addPending(items)`	Programmatically adds new `RedactionItem`s to the pending queue.
`removePending(page, id)`	Removes a specific pending redaction mark.
`clearPending()`	Removes all pending redaction marks.
`commitAllPending()`	(Destructive) Applies all pending redactions to the document. Returns a `Task`.
`commitPending(page, id)`	(Destructive) Applies a single pending redaction. Returns a `Task`.
`onStateChange(cb)`	Subscribes to any change in the `RedactionState`.
`onRedactionEvent(cb)`	Subscribes to events like adding, removing, or committing redactions.

Redaction Plugin

Operating Modes

Installation

Registration

Usage

1. Add the `<RedactionLayer />`

3. Create a Menu for Pending Marks

Live Example

Annotation Mode

Enabling Annotation Mode

Required Layers

Unified Redact Mode

Customizing Colors

API Reference

Configuration (`RedactionPluginConfig`)

Component: `<RedactionLayer />`

Snippet: `selectionMenu`

Store: `useRedaction(documentId)`

Parameters

Returns

`RedactionState` Properties

`RedactionScope` Methods

Need Help?

Redaction Plugin

Operating Modes

Installation

Registration

Usage

1. Add the <RedactionLayer />

2. Build a Redaction Toolbar

3. Create a Menu for Pending Marks

Live Example

Annotation Mode

Enabling Annotation Mode

Required Layers

Unified Redact Mode

Customizing Colors

API Reference

Configuration (RedactionPluginConfig)

Component: <RedactionLayer />

Snippet: selectionMenu

Store: useRedaction(documentId)

Parameters

Returns

RedactionState Properties

RedactionScope Methods

Need Help?

1. Add the `<RedactionLayer />`

Configuration (`RedactionPluginConfig`)

Component: `<RedactionLayer />`

Snippet: `selectionMenu`

Store: `useRedaction(documentId)`

`RedactionState` Properties

`RedactionScope` Methods