Pan Plugin

The Pan Plugin provides a “hand tool” that allows users to navigate the PDF by clicking and dragging the document within the viewport. This offers an intuitive alternative to using scrollbars, especially on touch devices.

Installation

This plugin depends on the Viewport and Interaction Manager plugins. You must install all three packages.

npm install @embedpdf/plugin-pan @embedpdf/plugin-viewport @embedpdf/plugin-interaction-manager

pnpm add @embedpdf/plugin-pan @embedpdf/plugin-viewport @embedpdf/plugin-interaction-manager

yarn add @embedpdf/plugin-pan @embedpdf/plugin-viewport @embedpdf/plugin-interaction-manager

bun add @embedpdf/plugin-pan @embedpdf/plugin-viewport @embedpdf/plugin-interaction-manager

Registration

Import PanPluginPackage and its dependencies, and add them to the plugins array. The Pan plugin is registered after its dependencies.

import { createPluginRegistration } from '@embedpdf/core'
// ... other imports
import { ViewportPluginPackage } from '@embedpdf/plugin-viewport/svelte'
import { InteractionManagerPluginPackage } from '@embedpdf/plugin-interaction-manager/svelte'
import { PanPluginPackage } from '@embedpdf/plugin-pan/svelte'
 
const plugins = [
  // ... other essential plugins
  createPluginRegistration(LoaderPluginPackage, { /* ... */ }),
  createPluginRegistration(RenderPluginPackage),
 
  // Register dependencies first
  createPluginRegistration(ViewportPluginPackage),
  createPluginRegistration(InteractionManagerPluginPackage),
 
  // Register and configure the pan plugin
  createPluginRegistration(PanPluginPackage, {
    defaultMode: 'mobile', // Automatically enable pan as default on touch devices
  }),
]

Usage

The plugin works by registering a “pan” interaction mode. You can build UI to toggle this mode on and off using the usePan composable.

Building a Pan Tool Button

The usePan composable provides the reactive isPanning state and a provides object with methods to control the pan mode. The isPanning boolean is perfect for providing visual feedback in your UI, such as highlighting the tool’s button when it is active.

<script lang="ts">
import { usePan } from '@embedpdf/plugin-pan/svelte';
 
const pan = usePan();
</script>
 
{#if pan.provides}
  <button
    onclick={() => pan.provides?.togglePan()}
    class:active={pan.isPanning}
  >
    Hand Tool
  </button>
{/if}

Using GlobalPointerProvider

For a smooth panning experience, it’s crucial that the viewer can track mouse movements even when the cursor moves outside the boundaries of the viewport. The GlobalPointerProvider component, exported from the Interaction Manager plugin, solves this by capturing events globally.

You should wrap your <Viewport> component with <GlobalPointerProvider> to enable this behavior.

<script lang="ts">
import { GlobalPointerProvider } from '@embedpdf/plugin-interaction-manager/svelte';
</script>
 
<GlobalPointerProvider>
  <Viewport>
    <Scroller>{/* ... */}</Scroller>
  </Viewport>
</GlobalPointerProvider>

Live Example

This example includes a toolbar button that toggles the pan mode. Click the hand tool icon to activate it, then click and drag the document to scroll.

API Reference

Configuration (PanPluginConfig)

Composable: usePan()

Connects your component to the pan plugin’s state and functions.

Returns

PanCapability Methods