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-manager

Registration

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 component

Usage

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:

ZoomToolbar.tsx
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.

Loading PDF Engine...

API Reference

Configuration (ZoomPluginConfig)

You can pass these options when registering the plugin with createPluginRegistration:

OptionTypeDescription
defaultZoomLevelZoomMode | numberThe 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
minZoomnumberThe minimum allowed numeric zoom level.
Default: 0.2
maxZoomnumberThe maximum allowed numeric zoom level.
Default: 60
presetsZoomPreset[]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

PropertyTypeDescription
stateZoomStateAn object containing the current zoom state.
providesZoomCapability | nullAn object with methods to control zooming, or null if the plugin is not ready.

ZoomState Properties

PropertyTypeDescription
currentZoomLevelnumberThe actual, calculated zoom factor applied to the document.
zoomLevelZoomMode | numberThe last requested zoom level, which might be a mode like 'fit-page'.

ZoomCapability Methods

MethodDescription
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

PropTypeDescription
pageIndexnumber(Required) The index of the page this component is rendered on.
scalenumber(Required) The current scale of the page.
classNamestring(Optional) An optional CSS class for custom styling of the marquee rectangle.
strokestring(Optional) The color of the rectangle’s border.
fillstring(Optional) The background color of the rectangle.
Last updated on October 27, 2025

Need Help?

Join our community for support, discussions, and to contribute to EmbedPDF's development.