Vue 2 & Vue 3 PDF Viewer Component

0.2.7 · active · verified Sun Apr 19

The `pdf-viewer-vue` package offers a straightforward Vue component for embedding and displaying PDF documents directly within Vue 2 and Vue 3 applications. It acts as a wrapper around the `vue-pdf` library, which itself leverages Mozilla's PDF.js for rendering PDF content. The current stable version is 0.2.7. This library is designed for developers seeking a basic, easy-to-integrate PDF viewer without the need for extensive customization or advanced interactive features like sophisticated annotations or form filling, which might be found in more comprehensive or commercially backed alternatives. Its release cadence has been infrequent, focusing primarily on maintaining compatibility with Vue versions 2 and 3.

Common errors

```
Failed to load PDF file: NetworkError when attempting to fetch resource.
```
cause The PDF file could not be fetched, most commonly due to Cross-Origin Resource Sharing (CORS) restrictions or an incorrect URL.

fix Verify the `src` prop URL is correct and accessible. If loading from a different domain, ensure the server hosting the PDF has appropriate `Access-Control-Allow-Origin` headers set to allow your application's domain.
```
The PDF viewer component is rendered, but no PDF content is visible (blank space).
```
cause The underlying canvas element used by PDF.js requires explicit dimensions (height and/or width) to render correctly within the DOM, which are often not automatically inherited.

fix Apply inline styles or CSS classes to the `<PdfViewer>` component or its immediate parent to give it a defined `height` and `width`, for example: `<PdfViewer src="..." style="height: 600px; width: 100%;" />`.
```
Uncaught TypeError: Cannot read properties of undefined (reading 'register')
```
cause This error can occur if the Vue application context is not correctly established when using the component, or if a global Vue instance is expected but not present (more common in Vue 2 or CDN setups).

fix Ensure Vue is properly initialized and the `PdfViewer` component is correctly imported and registered within your Vue component's `components` option or via `app.component()` in Vue 3.

Warnings

gotcha When loading PDFs from external domains, ensure that the server hosting the PDF has appropriate Cross-Origin Resource Sharing (CORS) headers configured. Without correct CORS headers, the browser's security policy will block the PDF from loading.
Fix: For development, use a local proxy or browser extensions to bypass CORS. For production, configure the hosting server (e.g., Apache, Nginx, S3 bucket) to include 'Access-Control-Allow-Origin: *' or specific origins for PDF files.
gotcha The component requires explicit height and width styles to render correctly, as the underlying PDF.js canvas element needs defined dimensions. If the viewer appears blank, it's often due to missing or incorrect sizing.
Fix: Always apply `height` and `width` styles to the `<PdfViewer>` component or its parent container. For example: `<PdfViewer :src="pdfUrl" style="height: 500px; width: 100%;" />`.
gotcha This package wraps `vue-pdf`, which in turn uses `pdf.js`. Issues related to `pdf.js` (e.g., compatibility with specific PDF features, rendering quirks, or `pdf.worker.js` loading) may apply and debugging might require understanding the underlying libraries.
Fix: Refer to the documentation and issue trackers for `vue-pdf` (FranckFreiburger/vue-pdf) and `pdf.js` (mozilla/pdf.js) for deeper insights into rendering problems or advanced configurations.
deprecated While the `pdf-viewer-vue` package explicitly supports both Vue 2 and Vue 3, Vue 2 is officially in its End of Life (EOL) phase as of December 31, 2023. Continuing new development on Vue 2 is generally discouraged.
Fix: For new projects, prioritize Vue 3. For existing Vue 2 projects, plan an upgrade path to Vue 3 to ensure long-term support and access to new features.

Install

npm install pdf-viewer-vue npm
yarn add pdf-viewer-vue yarn
pnpm add pdf-viewer-vue pnpm

Imports

PdfViewer

wrong:

import { PdfViewer } from 'pdf-viewer-vue';

correct:

import PdfViewer from 'pdf-viewer-vue';

The primary component is a default export from the package.

PdfViewer (within component)
wrong:
```
components: { 'pdf-viewer-vue': PdfViewer }
```
correct:
```
components: { PdfViewer }
```
When using in the Options API, register the component directly by its imported name.

Quickstart

This quickstart demonstrates how to integrate and display a PDF document using the PdfViewer component in a Vue 3 Composition API setup, with TypeScript.

<template>
  <div class="pdf-container">
    <h2>My Document Viewer</h2>
    <p>Displaying a sample PDF:</p>
    <PdfViewer src="https://www.africau.edu/images/default/sample.pdf" style="height: 500px; width: 100%;" />
    <p>This viewer supports both Vue 2 and Vue 3 applications.</p>
  </div>
</template>

<script lang="ts">
import { defineComponent } from 'vue';
import PdfViewer from 'pdf-viewer-vue';

export default defineComponent({
  name: 'DocumentViewer',
  components: {
    PdfViewer,
  },
  setup() {
    // Composition API specific logic can go here
  },
});
</script>

<style scoped>
.pdf-container {
  border: 1px solid #eee;
  padding: 20px;
  border-radius: 8px;
  max-width: 800px;
  margin: 20px auto;
  box-shadow: 0 2px 12px rgba(0,0,0,0.05);
}
</h2 style="color: #333;">
</style>

view raw JSON →