Pan (Hand Tool)

The Pan plugin provides a “hand tool” mode that allows users to click and drag to scroll the document. This is often preferred over text selection for navigation, especially on touch devices.

Configuration

You can configure when the pan tool should be active by default using the pan config object.


<template>
  <PDFViewer
    :config="{
      pan: {
        // 'mobile' | 'always' | 'never'
        defaultMode: 'mobile' 
      }
    }"
  />
</template>

Modes

Mode	Description
`'mobile'`	Default. Pan is enabled by default only on touch devices. Desktop users start in text selection mode.
`'always'`	Pan is always the default mode.
`'never'`	Text selection (or another mode) is always the default.

Programmatic Control

You can toggle the pan mode programmatically, for example, to build a custom toolbar.

Toggling Mode


<script setup lang="ts">
import { ref } from 'vue';
import { PDFViewer, type PluginRegistry, type PanPlugin } from '@embedpdf/vue-pdf-viewer';
 
const registry = ref<PluginRegistry | null>(null);
 
const handleReady = (r: PluginRegistry) => {
  registry.value = r;
};
 
const togglePan = () => {
  const panPlugin = registry.value?.getPlugin<PanPlugin>('pan')?.provides();
  const docPan = panPlugin?.forDocument('my-doc-id');
  docPan?.togglePan();
};
 
const enablePan = () => {
  const panPlugin = registry.value?.getPlugin<PanPlugin>('pan')?.provides();
  const docPan = panPlugin?.forDocument('my-doc-id');
  docPan?.enablePan();
};
 
const disablePan = () => {
  const panPlugin = registry.value?.getPlugin<PanPlugin>('pan')?.provides();
  const docPan = panPlugin?.forDocument('my-doc-id');
  docPan?.disablePan();
};
</script>
 
<template>
  <PDFViewer @ready="handleReady" :config="{ src: '/doc.pdf' }" />
</template>

Checking State


<script setup lang="ts">
const isPanning = () => {
  const panPlugin = registry.value?.getPlugin<PanPlugin>('pan')?.provides();
  const docPan = panPlugin?.forDocument('my-doc-id');
  return docPan?.isPanMode();
};
</script>

Listening for Changes

You can listen for changes in the interaction mode to update your UI.


<script setup lang="ts">
import { ref } from 'vue';
import { PDFViewer, type PluginRegistry } from '@embedpdf/vue-pdf-viewer';
 
const toolState = ref<'hand' | 'cursor'>('cursor');
 
const handleReady = (registry: PluginRegistry) => {
  const panPlugin = registry.getPlugin('pan')?.provides();
 
  // Subscribe to global changes
  panPlugin?.onPanModeChange(({ documentId, isPanMode }) => {
    console.log(`Document ${documentId} pan mode is now: ${isPanMode}`);
  });
 
  // Or subscribe to a specific document
  const docPan = panPlugin?.forDocument('my-doc');
  docPan?.onPanModeChange((isPanMode) => {
    toolState.value = isPanMode ? 'hand' : 'cursor';
  });
};
</script>
 
<template>
  <PDFViewer @ready="handleReady" :config="{ src: '/doc.pdf' }" />
</template>