Vue PDF Embed Component

2.1.4 · active · verified Sun Apr 19

vue-pdf-embed is a Vue 3 component designed for rendering PDF documents within web applications. It leverages PDF.js internally to provide features like controlled rendering, handling password-protected documents, and including interactive text and annotation layers. The current stable version is 2.1.4, released frequently with minor updates and patches, often updating its internal PDF.js dependency. Key differentiators include its simplicity, direct browser usability via unpkg, and lack of additional peer dependencies beyond Vue itself, making it easy to integrate into Vue 3 projects. It explicitly supports only Vue 3; for Vue 2, users must install `vue-pdf-embed@1`. It offers fine-grained control over PDF display, including page rotation, scaling, and selective page rendering.

Common errors

```
Failed to resolve import "vue-pdf-embed" from "src/App.vue". Does the file exist?
```
cause Using `vue-pdf-embed` in a CommonJS-only environment (e.g., older Node.js builds or specific bundler configurations) or an incorrect import path.

fix Ensure your project is configured for ES Modules (e.g., using Vite or Webpack 5 with appropriate loaders). The package is ESM-first. Double-check the import path `from 'vue-pdf-embed'`.
```
TypeError: Cannot read properties of null (reading 'style')
```
cause This error often occurs when the PDF rendering canvas or its parent elements are not properly mounted or styled, leading to null references during rendering attempts, sometimes related to `canvas styling` fixes in past versions.

fix Ensure the `VuePdfEmbed` component is mounted within a visible HTML element. Check for any custom CSS that might hide or interfere with the canvas elements. Update to the latest patch version (>=2.1.3) to benefit from canvas styling and null checks fixes.
```
Worker src not set. See GlobalWorkerOptions.workerSrc
```
cause The PDF.js worker script, essential for rendering PDFs, hasn't been properly configured or loaded. This can happen if using the 'essential build' or if `GlobalWorkerOptions.workerSrc` is not set explicitly when a custom worker is desired.

fix By default, `vue-pdf-embed` should handle the worker. If you're using an 'essential build' introduced in v2.0.0, you might need to manually set `GlobalWorkerOptions.workerSrc` to the path of the PDF.js worker script. For standard usage, ensure bundler settings allow worker loading.
```
Error: Unknown or unsupported PDF format.
```
cause The `source` prop is pointing to an invalid, corrupted, or non-PDF file, or the PDF is password-protected and no password was provided.

fix Verify that `pdfSource` is a valid URL or Base64 string of a correctly formatted PDF. If the PDF is password-protected, use the appropriate prop to provide the password.

Warnings

breaking Version 2.0.0 introduced significant breaking changes, switching exclusively to Vue 3 support, migrating to Vite for builds, and introducing TypeScript. Vue 2 projects must remain on `vue-pdf-embed@1`.
Fix: For Vue 2 projects, downgrade to `npm install vue-pdf-embed@1`. For Vue 3, ensure your project is set up for ES Modules and TypeScript if applicable.
breaking In v2.0.0, the package stopped injecting styles and now requires explicit imports for text and annotation layers. The structure for styles also changed.
Fix: Manually import `vue-pdf-embed/dist/styles/annotationLayer.css` and `vue-pdf-embed/dist/styles/textLayer.css` if you need text selection and annotations.
breaking Version 2.1.0 renamed the styles directory and inlined essential styles. While `dist/styles/index.css` is no longer required, specific layers still need importing.
Fix: Verify your style imports. Ensure `vue-pdf-embed/dist/styles/*.css` paths are correct. The core styles are now inlined, simplifying basic usage, but text and annotation layers still require explicit imports.
gotcha The `imageResourcesPath` prop might need to be configured if icons for the annotation layer are not loading correctly, especially in non-standard deployment environments.
Fix: Set the `imageResourcesPath` prop to the correct URL or path with a trailing slash where the annotation layer icons are accessible.
gotcha When using the component in environments with strict Content Security Policy (CSP), ensure that `script-src` and `worker-src` directives allow loading of the PDF.js worker, as it's critical for rendering.
Fix: Adjust your CSP to permit the loading of web workers. For example, `worker-src 'self' blob:;` and `script-src 'self' 'unsafe-inline' 'unsafe-eval';` (adjust as per security requirements).

Install

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

Imports

VuePdfEmbed
wrong:
```
const VuePdfEmbed = require('vue-pdf-embed')
```
correct:
```
import VuePdfEmbed from 'vue-pdf-embed'
```
This package is ESM-first and primarily designed for Vue 3's SFC setup. CommonJS require is not supported.
styles
wrong:
```
import 'vue-pdf-embed/dist/annotationLayer.css'
```
correct:
```
import 'vue-pdf-embed/dist/styles/annotationLayer.css';
import 'vue-pdf-embed/dist/styles/textLayer.css';
```
Since v2.1.0, styles are located under `dist/styles/`. Essential styles are inlined, but `annotationLayer.css` and `textLayer.css` still need explicit imports for full functionality.
Composable (Internal)
```
import { usePdfEmbed } from 'vue-pdf-embed';
```
Exposes an internal composable for advanced use cases like programmatically loading PDFs or accessing methods like download and print. Primarily for advanced customization.

Quickstart

This quickstart demonstrates how to embed a PDF using `VuePdfEmbed`, including importing necessary styles, setting the PDF source, and dynamically controlling page navigation and rotation with reactive Vue refs.

<script setup>
import { ref } from 'vue';
import VuePdfEmbed from 'vue-pdf-embed';

// Optional styles for text selection and annotations
import 'vue-pdf-embed/dist/styles/annotationLayer.css';
import 'vue-pdf-embed/dist/styles/textLayer.css';

const pdfSource = ref('https://example.com/sample.pdf'); // Replace with your PDF URL
const page = ref(1);
const rotation = ref(0);

// Example of changing page or rotation dynamically
function goToNextPage() {
  page.value++;
}

function rotatePdf() {
  rotation.value = (rotation.value + 90) % 360;
}
</script>

<template>
  <div>
    <h1>My Document Viewer</h1>
    <button @click="goToNextPage">Next Page</button>
    <button @click="rotatePdf">Rotate PDF</button>
    <VuePdfEmbed 
      annotation-layer 
      text-layer 
      :source="pdfSource" 
      :page="page" 
      :rotation="rotation"
      height="500"
    />
  </div>
</template>

view raw JSON →