Zoom Plugin
The Zoom Plugin provides a comprehensive set of tools for controlling the magnification of PDF documents. It supports standard zoom-in/out, preset zoom levels (like fit-to-page and fit-to-width), and an interactive marquee zoom (also known as area zoom).
Installation
This plugin is available as a separate package. You’ll also need the interaction-manager plugin if you plan to use the marquee zoom feature.
npm install @embedpdf/plugin-zoom @embedpdf/plugin-interaction-managerRegistration
Import ZoomPluginPackage and, if needed, InteractionManagerPluginPackage. Add them to the plugins array passed to the <EmbedPDF> component. You can configure the default zoom behavior upon registration.
import { createPluginRegistration } from '@embedpdf/core'
import { EmbedPDF } from '@embedpdf/core/react'
// ... other imports
import {
ZoomPluginPackage,
ZoomMode,
} from '@embedpdf/plugin-zoom/react'
import { InteractionManagerPluginPackage } from '@embedpdf/plugin-interaction-manager/react'
const plugins = [
// ... other essential plugins like Loader, Viewport, etc.
createPluginRegistration(LoaderPluginPackage, {
/* ... */
}),
createPluginRegistration(ViewportPluginPackage),
createPluginRegistration(ScrollPluginPackage),
createPluginRegistration(RenderPluginPackage),
// Register the interaction manager (required for marquee zoom)
createPluginRegistration(InteractionManagerPluginPackage),
// Register and configure the zoom plugin
createPluginRegistration(ZoomPluginPackage, {
// Set the initial zoom level when a document loads
defaultZoomLevel: ZoomMode.FitPage,
}),
]
// ... rest of your componentUsage
The plugin exposes the useZoom hook to connect your UI components to its logic and state, and the <MarqueeZoom /> component for area selection.
Building a Zoom Toolbar
The useZoom hook is the primary way to interact with the plugin. It returns the current zoom state and a provides object with methods to change the zoom.
Here’s how you can build a custom toolbar:
import { useZoom } from '@embedpdf/plugin-zoom/react'
export const ZoomToolbar = () => {
const { provides: zoom, state } = useZoom()
if (!zoom) {
return null
}
return (
<div className="toolbar">
{/* Display current zoom */}
<span>{Math.round(state.currentZoomLevel * 100)}%</span>
{/* Buttons to control zoom */}
<button onClick={zoom.zoomOut}>-</button>
<button onClick={zoom.zoomIn}>+</button>
<button onClick={() => zoom.requestZoom(1.0)}>Reset</button>
{/* Button to toggle area zoom mode */}
<button onClick={zoom.toggleMarqueeZoom}>Area Zoom</button>
</div>
)
}To have the “Area Zoom” button visually reflect its active state, you would also use a hook from the Interaction Manager plugin to check the currently active mode.
Adding Marquee (Area) Zoom
The marquee zoom feature allows users to click and drag a rectangle on a page to zoom into that specific area.
To enable this, place the <MarqueeZoom /> component inside the renderPage prop of your <Scroller />. This component will automatically render the selection rectangle when the marquee mode is active.
import { PagePointerProvider } from '@embedpdf/plugin-interaction-manager/react';
// Inside your main PDFViewer component
<Scroller
renderPage={({ width, height, pageIndex, scale, rotation }) => (
<PagePointerProvider
pageIndex={pageIndex}
pageWidth={width}
pageHeight={height}
rotation={rotation}
scale={scale}
>
{/* Base render layer - renders a low resolution version of the entire page for immediate display */}
<RenderLayer pageIndex={pageIndex} scale={1} />
{/* Tiling layer - renders high resolution tiles only for the visible area, scales with zoom level */}
<TilingLayer pageIndex={pageIndex} scale={scale} />
{/* Marquee layer for area zoom */}
<MarqueeZoom pageIndex={pageIndex} scale={scale} />
</PagePointerProvider>
)}
/>This requires the interaction-manager plugin to be registered. When a user clicks the “Area Zoom” button in the toolbar, toggleMarqueeZoom activates the mode, and the <MarqueeZoom /> component handles the user’s drag-and-drop interaction.
Live Example
This example combines the toolbar and the marquee zoom component into a complete viewer. Try clicking the area zoom button (the icon with the magnifying glass and crosshairs) and dragging a rectangle over the document.
API Reference
Configuration (ZoomPluginConfig)
You can pass these options when registering the plugin with createPluginRegistration:
| Option | Type | Description |
|---|---|---|
defaultZoomLevel | ZoomMode | number | The initial zoom level. Can be a numeric scale factor (e.g., 1.5 for 150%) or a ZoomMode enum (ZoomMode.Automatic, ZoomMode.FitPage, ZoomMode.FitWidth). Default: ZoomMode.Automatic |
minZoom | number | The minimum allowed numeric zoom level. Default: 0.2 |
maxZoom | number | The maximum allowed numeric zoom level. Default: 60 |
presets | ZoomPreset[] | An array of objects { name: string, value: ZoomMode | number } to define options for a zoom dropdown menu in your UI. Use provides.getPresets() to retrieve this list. |
Hook: useZoom()
This hook connects your component to the zoom plugin’s state and functions.
Returns
| Property | Type | Description |
|---|---|---|
state | ZoomState | An object containing the current zoom state. |
provides | ZoomCapability | null | An object with methods to control zooming, or null if the plugin is not ready. |
ZoomState Properties
| Property | Type | Description |
|---|---|---|
currentZoomLevel | number | The actual, calculated zoom factor applied to the document. |
zoomLevel | ZoomMode | number | The last requested zoom level, which might be a mode like 'fit-page'. |
ZoomCapability Methods
| Method | Description |
|---|---|
zoomIn() | Zooms in by one step. |
zoomOut() | Zooms out by one step. |
requestZoom(level) | Sets the zoom to a specific level (e.g., 1.0 or ZoomMode.FitWidth). |
toggleMarqueeZoom() | Enables or disables the area zoom mode. |
isMarqueeZoomActive() | Returns true if area zoom is currently active. |
getPresets() | Returns the array of presets from the configuration. |
Component: <MarqueeZoom />
Renders the visual rectangle when a user is selecting an area to zoom into.
Props
| Prop | Type | Description |
|---|---|---|
pageIndex | number | (Required) The index of the page this component is rendered on. |
scale | number | (Required) The current scale of the page. |
className | string | (Optional) An optional CSS class for custom styling of the marquee rectangle. |
stroke | string | (Optional) The color of the rectangle’s border. |
fill | string | (Optional) The background color of the rectangle. |
Need Help?
Join our community for support, discussions, and to contribute to EmbedPDF's development.