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.


<script setup lang="ts">
import { createPluginRegistration } from '@embedpdf/core';
import { EmbedPDF } from '@embedpdf/core/vue';
// ... other imports
import { DocumentManagerPluginPackage } from '@embedpdf/plugin-document-manager/vue';
import { ZoomPluginPackage, ZoomMode } from '@embedpdf/plugin-zoom/vue';
 
const plugins = [
  // ... other essential plugins like DocumentManager, Viewport, etc.
  createPluginRegistration(DocumentManagerPluginPackage, {
    initialDocuments: [{ url: 'https://snippet.embedpdf.com/ebook.pdf' }],
  }),
  createPluginRegistration(ViewportPluginPackage),
  createPluginRegistration(ScrollPluginPackage),
  createPluginRegistration(RenderPluginPackage),
 
  // Add the zoom plugin to the array
  createPluginRegistration(ZoomPluginPackage, {
    defaultZoomLevel: ZoomMode.FitPage, // You can pass options here!
  }),
];
</script>

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 Composables

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

Since EmbedPDF supports multiple documents, composables and components require a documentId parameter to know which document they’re working with. You’ll get the activeDocumentId from the <EmbedPDF> component’s scoped slot.

ZoomToolbar.vue


<script setup lang="ts">
import { useZoom } from '@embedpdf/plugin-zoom/vue';
 
const props = defineProps<{
  documentId: string;
}>();
 
// Pass the documentId as a getter function
const { provides: zoomProvides, state: zoomState } = useZoom(() => props.documentId);
</script>
 
<template>
  <div v-if="zoomProvides">
    <span>Current Zoom: {{ Math.round(zoomState.currentZoomLevel * 100) }}%</span>
    <button @click="zoomProvides.zoomOut()">-</button>
    <button @click="zoomProvides.zoomIn()">+</button>
    <button @click="() => zoomProvides.requestZoom(1.0)">Reset</button>
  </div>
</template>

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 composable to access the context provided by the ZoomPluginPackage.

Since we’re working with multiple documents, you’ll need to:

Get the activeDocumentId from the <EmbedPDF> scoped slot
Use <DocumentContent> to ensure the document is loaded before rendering
Pass the documentId to all components and composables that need it

PDFViewer.vue


<script setup lang="ts">
import { EmbedPDF } from '@embedpdf/core/vue';
import { DocumentContent } from '@embedpdf/plugin-document-manager/vue';
import { Viewport } from '@embedpdf/plugin-viewport/vue';
import { Scroller } from '@embedpdf/plugin-scroll/vue';
import { RenderLayer } from '@embedpdf/plugin-render/vue';
import ZoomToolbar from './ZoomToolbar.vue'; // 1. Import the toolbar
// ... plugins array setup
</script>
 
<template>
  <div style="height: 500px; border: 1px solid black; display: flex; flex-direction: column">
    <EmbedPDF :engine="engine" :plugins="plugins" v-slot="{ activeDocumentId }">
      <DocumentContent 
        v-if="activeDocumentId" 
        :document-id="activeDocumentId" 
        v-slot="{ isLoaded }"
      >
        <template v-if="isLoaded">
          <div style="display: flex; height: 100%; flex-direction: column">
            <!-- 2. Add the component here with documentId -->
            <ZoomToolbar :document-id="activeDocumentId" />
            <div style="flex: 1; overflow: hidden">
              <Viewport :document-id="activeDocumentId">
                <Scroller :document-id="activeDocumentId">
                  <template #default="{ page }">
                    <div :style="{ width: page.width + 'px', height: page.height + 'px' }">
                      <RenderLayer 
                        :document-id="activeDocumentId" 
                        :page-index="page.pageIndex" 
                      />
                    </div>
                  </template>
                </Scroller>
              </Viewport>
            </div>
          </div>
        </template>
      </DocumentContent>
    </EmbedPDF>
  </div>
</template>

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).
Vue Components: Most plugins offer functional components that you place in your viewer to add UI features (e.g., <RenderLayer />, <SelectionLayer />, <MarqueeZoom />).
Vue Composables: Functions like useZoom(() => documentId) or useScroll(() => documentId) allow your custom components to access plugin data and trigger actions. Since EmbedPDF supports multiple documents, these composables require a documentId parameter (as a getter function).

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