VuePDF Documentation

VuePDF is a component designed for Vue 3 that allows you to render PDF pages on your website in a dynamic and customizable way.

Key features include:

• Sizing: Control page dimensions via scale, width, height, or by fitting the PDF page to the parent width.
• Text Highlighting: Capability to search and highlight text within the PDF.
• Watermarking: Add watermarks to pages to protect content.
• Content Layers: Support for text selection, annotations, and XFA forms through specialized layers.

The PDFCommentAnnotation component renders a built-in popup for annotations with comments. The popup displays the creation date, text content, and edit/delete buttons (when selected).

Interactions:

• Hover: Shows the popup temporarily.
• Click: Selects the popup, keeping it visible and revealing edit and delete controls.

For legacy browser support, you must manually configure the pdfjs-dist legacy worker before calling usePDF. This must be done on the main thread.

<script setup lang="ts">
import * as PDFJS from 'pdfjs-dist';
import LegacyWorker from 'pdfjs-dist/legacy/build/pdf.worker.min?url';
import { VuePDF, usePDF } from '@tato30/vue-pdf';

PDFJS.GlobalWorkerOptions.workerSrc = LegacyWorker

const { pdf } = usePDF(/** */)
</script>

To enable annotation editing, you must enable the editor-layer prop on the VuePDF component.

Critical Requirement: For the editor layer to function, both text-layer and annotation-layer props must also be set to true. If either is disabled, the editor behavior will break.

You must also provide editor configuration components inside the editors slot to define how different annotation types behave.

<script setup>
import { ref } from 'vue'
import { VuePDF, usePDF } from '@tato30/vue-pdf'
import '@tato30/vue-pdf/style.css'

const { pdf } = usePDF('document.pdf')
const editorType = ref(0)
</script>

<template>
  <VuePDF
    :pdf="pdf"
    text-layer
    annotation-layer
    editor-layer
    :editor-type="editorType"
  >
    <template #editors>
      <!-- Place editor components here -->
    </template>
  </VuePDF>
</template>

If you pass a ref instead of a plain string or URL to usePDF, the returned values (pdf, pages, info) will automatically update whenever the value of the ref changes. This is useful for switching between different PDF documents dynamically.

<script setup>
import { ref } from 'vue'
import { VuePDF, usePDF } from '@tato30/vue-pdf'

// Changing currentPdf value will change pdf, pages and info values
const currentPdf = ref('sample.pdf')
const { pdf, pages, info } = usePDF(currentPdf)
</script>

<template>
  <VuePDF :pdf="pdf" />
</template>

The default slot in <VuePDF> allows you to render custom content while the PDF page rendering task is in progress. This is useful for displaying loading spinners or progress indicators.

<template>
  <VuePDF :pdf="pdf">
    <div>
      Loading...
    </div>
  </VuePDF>
</template>

The PDFFreeTextAnnotation component allows you to configure and customize the free text annotation editor. It enables users to add text annotations directly onto a PDF page.

Using this component is optional. If you do not use it, the free text editor will still function using default parameters, provided that the editor-type prop on the VuePDF component is set to 3.

To use it, place PDFFreeTextAnnotation within the #editors slot of the VuePDF component.

<template>
  <VuePDF :pdf="pdf" text-layer annotation-layer editor-layer :editor-type="3">
    <template #editors>
      <PDFFreeTextAnnotation :color="color" :fontSize="fontSize" />
    </template>
  </VuePDF>
</template>

If you need to reduce bundle size or host the PDF worker separately, use the @tato30/vue-pdf/minimal entry point. You must manually set GlobalWorkerOptions.workerSrc from pdfjs-dist before calling usePDF.

Important: The worker script version must match your pdfjs-dist version.

import { GlobalWorkerOptions } from 'pdfjs-dist'
import { VuePDF, usePDF } from '@tato30/vue-pdf/minimal'

GlobalWorkerOptions.workerSrc = 'https://unpkg.com/pdfjs-dist@5.4.296/build/pdf.worker.min.mjs'

const { pdf } = usePDF('sample.pdf')

VuePDF supports the pdf.js annotation editor, allowing users to create/edit annotations like FreeText, Highlight, Ink, and Stamp.

To use it:

1. Set the editor-layer prop on VuePDF.
2. Provide an :editor-type prop.
3. Use the #editors slot to mount the specific annotation component (e.g., PDFFreeTextAnnotation).

<script setup>
import { ref } from 'vue'
import { VuePDF, usePDF, PDFFreeTextAnnotation } from '@tato30/vue-pdf'
import '@tato30/vue-pdf/style.css'

const { pdf } = usePDF('sample.pdf')
const editorType = ref(3)
</script>

<template>
  <VuePDF :pdf="pdf" text-layer annotation-layer editor-layer :editor-type="editorType">
    <template #editors>
      <PDFFreeTextAnnotation color="#2196F3" :fontSize="20" />
    </template>
  </VuePDF>
</template>

The PDFInkAnnotation component enables a freehand ink/drawing annotation editor on a PDF page.

Note: Using this component is optional. If you do not use it, the ink editor will still function using default parameters, provided that the editor-type prop on the VuePDF component is set to 15. Use PDFInkAnnotation when you need to customize drawing parameters (color, thickness, opacity) or listen to annotation lifecycle events.

To use it, place the component within the #editors slot of the VuePDF component.

<template>
  <VuePDF :pdf="pdf" text-layer annotation-layer editor-layer :editor-type="15">
    <template #editors>
      <PDFInkAnnotation :color="color" :thickness="thickness" :opacity="opacity" />
    </template>
  </VuePDF>
</template>