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.
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-managerRegistration
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/vue'
import { SelectionPluginPackage } from '@embedpdf/plugin-selection/vue'
import { RedactionPluginPackage } from '@embedpdf/plugin-redaction/vue'
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 composable.
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 default slot and be a child of the <PagePointerProvider>.
<script setup lang="ts">
import { PagePointerProvider } from '@embedpdf/plugin-interaction-manager/vue';
import { RedactionLayer } from '@embedpdf/plugin-redaction/vue';
</script>
<template>
<Scroller :document-id="activeDocumentId">
<template #default="{ page }">
<PagePointerProvider :document-id="activeDocumentId" :page-index="page.pageIndex">
<RenderLayer :document-id="activeDocumentId" :page-index="page.pageIndex" />
<SelectionLayer :document-id="activeDocumentId" :page-index="page.pageIndex" />
<RedactionLayer :document-id="activeDocumentId" :page-index="page.pageIndex" />
</PagePointerProvider>
</template>
</Scroller>
</template>2. Build a Redaction Toolbar
The useRedaction composable 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 setup lang="ts">
import { useRedaction } from '@embedpdf/plugin-redaction/vue';
const props = defineProps<{ documentId: string }>();
const { state, provides } = useRedaction(() => props.documentId);
</script>
<template>
<div v-if="provides">
<button @click="provides.toggleRedactSelection()">Mark Text</button>
<button @click="provides.toggleMarqueeRedact()">Mark Area</button>
<span>{{ state.pendingCount }} pending marks</span>
<button
@click="provides.commitAllPending()"
:disabled="state.pendingCount === 0"
>
Apply All Redactions
</button>
</div>
</template>3. Create a Menu for Pending Marks
You can provide a selection-menu scoped slot 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 setup lang="ts">
import { RedactionLayer, useRedaction } from '@embedpdf/plugin-redaction/vue';
const props = defineProps<{ documentId: string }>();
const { provides } = useRedaction(() => props.documentId);
</script>
<template>
<RedactionLayer :document-id="documentId" :page-index="page.pageIndex">
<template #selection-menu="{ selected, context, menuWrapperProps, rect }">
<div v-if="selected" v-bind="menuWrapperProps">
<div
:style="{
position: 'absolute',
top: `${rect.size.height + 10}px`,
left: 0,
pointerEvents: 'auto'
}"
>
<button @click="provides?.removePending(context.item.page, context.item.id)">Remove</button>
</div>
</div>
</template>
</RedactionLayer>
</template>Live Example
This example demonstrates the full redaction workflow. Use the “Mark Text” and “Mark Area” buttons to queue redactions. Click a pending mark to see the option to remove it. Finally, click “Apply All” to permanently redact the content.
API Reference
Configuration (RedactionPluginConfig)
| Option | Type | Description |
|---|---|---|
drawBlackBoxes | boolean | If true, a black rectangle is drawn over the redacted content after committing. Default: true |
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. |
Scoped Slot: selection-menu
The <RedactionLayer> provides a scoped slot to render a custom menu when a pending redaction is selected.
| Prop | Type | Description |
|---|---|---|
context | object | The context containing the item (the pending redaction). |
selected | boolean | true if a pending redaction is currently selected. |
menuWrapperProps | object | Vue props to bind to your menu’s wrapper element for positioning. |
rect | Rect | The bounding box of the selected pending redaction. |
Composable: 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 | Ref<RedactionScope | null> | A ref 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 ('marqueeRedact' or 'redactSelection'). |
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 |
|---|---|
toggleRedactSelection() | Toggles the text redaction mode. |
toggleMarqueeRedact() | Toggles the area redaction mode. |
addPending(items) | Programmatically adds new RedactionItems 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. |
Need Help?
Join our community for support, discussions, and to contribute to EmbedPDF's development.