Capture Plugin
The Capture Plugin provides a “snapshot” tool, allowing users to select a rectangular area (a marquee) on any page and export that specific section as a high-resolution image.
Installation
This plugin depends on the Render and Interaction Manager plugins. You must install all three packages.
npm install @embedpdf/plugin-capture @embedpdf/plugin-render @embedpdf/plugin-interaction-managerRegistration
Import CapturePluginPackage and its dependencies, then add them to the plugins array. The dependencies should be registered before the capture plugin.
import { createPluginRegistration } from '@embedpdf/core'
import { EmbedPDF } from '@embedpdf/core/react'
// ... other imports
import { RenderPluginPackage } from '@embedpdf/plugin-render/react'
import { InteractionManagerPluginPackage } from '@embedpdf/plugin-interaction-manager/react'
import { CapturePluginPackage } from '@embedpdf/plugin-capture/react'
const plugins = [
// ... other essential plugins
createPluginRegistration(LoaderPluginPackage, { /* ... */ }),
createPluginRegistration(ViewportPluginPackage),
createPluginRegistration(ScrollPluginPackage),
// Register dependencies first
createPluginRegistration(RenderPluginPackage),
createPluginRegistration(InteractionManagerPluginPackage),
// Register and configure the capture plugin
createPluginRegistration(CapturePluginPackage, {
scale: 2.0, // Render captured image at 2x resolution
imageType: 'image/png',
withAnnotations: true,
}),
]Usage
The plugin works by combining a UI component to draw the selection area, a hook to control the capture mode, and an event listener to handle the final image.
1. Add the <MarqueeCapture /> Component
To enable the visual selection tool, place the <MarqueeCapture /> component inside the renderPage prop of your <Scroller />. It must be a child of <PagePointerProvider> to correctly handle mouse or touch interactions.
import { PagePointerProvider } from '@embedpdf/plugin-interaction-manager/react';
import { MarqueeCapture } from '@embedpdf/plugin-capture/react';
// ...
<Scroller
renderPage={({ width, height, pageIndex, scale, rotation }) => (
<PagePointerProvider {...{ pageIndex, width, height, scale, rotation }}>
<RenderLayer pageIndex={pageIndex} />
<MarqueeCapture pageIndex={pageIndex} scale={scale} />
</PagePointerProvider>
)}
/>2. Build a Toolbar Button
Use the useCaptureCapability hook to get access to the plugin’s methods. The toggleMarqueeCapture() method activates and deactivates the selection mode.
import { useCaptureCapability } from '@embedpdf/plugin-capture/react';
const CaptureToolbar = () => {
const { provides: capture } = useCaptureCapability();
const isActive = capture?.isMarqueeCaptureActive();
return (
<button onClick={() => capture?.toggleMarqueeCapture()}>
{isActive ? 'Cancel' : 'Capture Area'}
</button>
);
}3. Handle the Captured Image
After the user selects an area, the plugin fires an event with the resulting image data. You must listen for this event using the onCaptureArea method to receive the Blob. From there, you can display the image or trigger a download.
import { useEffect, useState } from 'react';
import { useCaptureCapability, CaptureAreaEvent } from '@embedpdf/plugin-capture/react';
const CaptureResult = () => {
const { provides: capture } = useCaptureCapability();
const [imageUrl, setImageUrl] = useState<string | null>(null);
useEffect(() => {
if (!capture) return;
const unsubscribe = capture.onCaptureArea((result: CaptureAreaEvent) => {
const newUrl = URL.createObjectURL(result.blob);
setImageUrl(newUrl);
});
return () => {
unsubscribe();
if (imageUrl) URL.revokeObjectURL(imageUrl);
};
}, [capture]);
if (!imageUrl) return <p>Select an area to capture.</p>;
return <img src={imageUrl} alt="Captured PDF area" />;
};Live Example
Click the “Capture Area” button, then click and drag a rectangle over the PDF. The selected area will appear below as an image, with a button to download it.
API Reference
Configuration (CapturePluginConfig)
| Option | Type | Description |
|---|---|---|
scale | number | The resolution multiplier for the captured image. A value of 2 means 2x resolution. Default: 1 |
imageType | string | The image format, e.g., 'image/png', 'image/jpeg'. Default: 'image/png' |
withAnnotations | boolean | If true, annotations will be included in the captured image. Default: false |
Component: <MarqueeCapture />
The component that renders the visual selection rectangle.
| Prop | Type | Description |
|---|---|---|
pageIndex | number | (Required) The page index this component is rendered on. |
scale | number | (Required) The current scale of the page. |
className | string | Optional CSS class for custom styling of the marquee. |
stroke | string | The color of the marquee’s border. |
fill | string | The background color of the marquee. |
Hook: useCaptureCapability()
Connects your component to the capture plugin’s state and functions.
Returns
| Property | Type | Description |
|---|---|---|
provides | CaptureCapability | null | An object with methods to interact with the plugin, or null if not ready. |
CaptureCapability Methods
| Method | Description |
|---|---|
toggleMarqueeCapture() | Toggles the marquee selection mode on or off. |
isMarqueeCaptureActive() | Returns true if the marquee selection mode is currently active. |
onCaptureArea(callback) | Subscribes to the capture event. The callback receives a CaptureAreaEvent object when an area is successfully captured. |
captureArea(pageIndex, rect) | Programmatically captures a specified rectangular area on a page. |
Event: CaptureAreaEvent
The object passed to the onCaptureArea callback after a successful capture.
| Property | Type | Description |
|---|---|---|
pageIndex | number | The index of the page where the capture occurred. |
rect | Rect | An object describing the position and size of the captured area in PDF points. |
blob | Blob | The captured image data as a Blob object. |
imageType | string | The MIME type of the captured image (e.g., 'image/png'). |
scale | number | The resolution scale factor used for the capture. |
Need Help?
Join our community for support, discussions, and to contribute to EmbedPDF's development.