Understanding Plugins

Plugins are the heart of EmbedPDF’s headless architecture. They are modular packages that add specific features and capabilities to your core viewer. This à la carte approach ensures your application remains lean, loading only the functionality you actually need.

Think of the <EmbedPDF> component as a smartphone: it’s powerful on its own, but it’s the apps (plugins) you install that give it new features like navigation, social media, or games.

How Plugins Work

Adding a new feature to your viewer follows a simple three-step process:

1. Install the Plugin Package

Each plugin is its own NPM package. For example, to add zooming capabilities, you would install the zoom plugin:

npm install @embedpdf/plugin-zoom

pnpm add @embedpdf/plugin-zoom

yarn add @embedpdf/plugin-zoom

bun add @embedpdf/plugin-zoom

2. Register the Plugin

Next, you import the plugin’s ...PluginPackage and register it in the plugins array that you pass to the <EmbedPDF> component. This is done using the createPluginRegistration helper function.

import { createPluginRegistration } from '@embedpdf/core';
import { EmbedPDF } from '@embedpdf/core/react';
// ... other imports
import { ZoomPluginPackage } from '@embedpdf/plugin-zoom';
 
const plugins = [
  // ... other essential plugins like Loader, Viewport, etc.
  createPluginRegistration(LoaderPluginPackage, { /* ... */ }),
  createPluginRegistration(ViewportPluginPackage),
  createPluginRegistration(ScrollPluginPackage),
  createPluginRegistration(RenderPluginPackage),
 
  // Add the zoom plugin to the array
  createPluginRegistration(ZoomPluginPackage, {
    defaultZoomLevel: 1.5, // You can pass options here!
  }),
];
 
// ... rest of your component

Registering the plugin activates its core logic and makes its features available to the rest of your application.

3. Use the Plugin’s Components and Hooks

Once a plugin is registered, you can use its associated React components and hooks to build your UI. For example, the zoom plugin provides a <MarqueeZoom /> component for drag-to-zoom functionality and a useZoom hook to control zoom levels from a toolbar.

import { useZoom } from '@embedpdf/plugin-zoom/react';
 
export const ZoomToolbar = () => {
  const { provides: zoomProvides, state: zoomState } = useZoom();
 
  if (!zoomProvides) {
    return null;
  }
 
  return (
    <div>
      <span>Current Zoom: {Math.round(zoomState.currentZoomLevel * 100)}%</span>
      <button onClick={zoomProvides.zoomOut}>-</button>
      <button onClick={zoomProvides.zoomIn}>+</button>
      <button onClick={() => zoomProvides.requestZoom(1.0))}>Reset</button>
    </div>
  );
};

This clear separation of logic (the plugin) from the view (your components) gives you complete control over your UI.

4. Add the Component to Your Viewer

Finally, import and place your new <ZoomToolbar /> component inside the <EmbedPDF> provider. This is essential, as it allows the useZoom hook to access the context provided by the ZoomPluginPackage.

import { EmbedPDF } from '@embedpdf/core/react';
// ... other imports
import { Viewport } from '@embedpdf/plugin-viewport/react';
import { ZoomToolbar } from './ZoomToolbar'; // 1. Import the toolbar
 
// ... plugins array and PDFViewer component setup
export const PDFViewer = () => {
  // ...
  return (
    <div style={{ height: '500px', border: '1px solid black', display: 'flex', flexDirection: 'column' }}>
      <EmbedPDF engine={engine} plugins={plugins}>
        <div style={{display: 'flex, height: '100%', flexDirection: 'column'}}>
          <ZoomToolbar /> {/* 2. Add the component here */}
          <div style={{ flex: 1, overflow: 'hidden' }}>
            <Viewport>
              {/* ... Scroller and RenderLayer ... */}
            </Viewport>
          </div>
        </div>
      </EmbedPDF>
    </div>
  );
};

5. Live Demo

This is the result of the code above—a fully functional PDF viewer with zoom controls that you built from the ground up.

Types of Plugin Features

Plugins can provide several types of tools:

• Core Logic: Some plugins work entirely in the background to manage state (e.g., ScrollPluginPackage).
• React Components: Most plugins offer functional components that you place in your viewer to add UI features (e.g., <RenderLayer />, <SelectionLayer />, <MarqueeZoom />).
• React Hooks: Functions like useZoom() or useSearch() allow your custom components to access plugin data and trigger actions.

By combining plugins, you can compose a feature-rich PDF experience that is perfectly tailored to your application’s design and needs.