{"id":12541,"library":"vue-pdf-embed","title":"Vue PDF Embed Component","description":"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.","status":"active","version":"2.1.4","language":"javascript","source_language":"en","source_url":"https://github.com/hrynko/vue-pdf-embed","tags":["javascript","vue","vuejs","pdf","typescript"],"install":[{"cmd":"npm install vue-pdf-embed","lang":"bash","label":"npm"},{"cmd":"yarn add vue-pdf-embed","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-pdf-embed","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for the Vue component runtime.","package":"vue","optional":false}],"imports":[{"note":"This package is ESM-first and primarily designed for Vue 3's SFC setup. CommonJS require is not supported.","wrong":"const VuePdfEmbed = require('vue-pdf-embed')","symbol":"VuePdfEmbed","correct":"import VuePdfEmbed from 'vue-pdf-embed'"},{"note":"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.","wrong":"import 'vue-pdf-embed/dist/annotationLayer.css'","symbol":"styles","correct":"import 'vue-pdf-embed/dist/styles/annotationLayer.css';\nimport 'vue-pdf-embed/dist/styles/textLayer.css';"},{"note":"Exposes an internal composable for advanced use cases like programmatically loading PDFs or accessing methods like download and print. Primarily for advanced customization.","symbol":"Composable (Internal)","correct":"import { usePdfEmbed } from 'vue-pdf-embed';"}],"quickstart":{"code":"<script setup>\nimport { ref } from 'vue';\nimport VuePdfEmbed from 'vue-pdf-embed';\n\n// Optional styles for text selection and annotations\nimport 'vue-pdf-embed/dist/styles/annotationLayer.css';\nimport 'vue-pdf-embed/dist/styles/textLayer.css';\n\nconst pdfSource = ref('https://example.com/sample.pdf'); // Replace with your PDF URL\nconst page = ref(1);\nconst rotation = ref(0);\n\n// Example of changing page or rotation dynamically\nfunction goToNextPage() {\n  page.value++;\n}\n\nfunction rotatePdf() {\n  rotation.value = (rotation.value + 90) % 360;\n}\n</script>\n\n<template>\n  <div>\n    <h1>My Document Viewer</h1>\n    <button @click=\"goToNextPage\">Next Page</button>\n    <button @click=\"rotatePdf\">Rotate PDF</button>\n    <VuePdfEmbed \n      annotation-layer \n      text-layer \n      :source=\"pdfSource\" \n      :page=\"page\" \n      :rotation=\"rotation\"\n      height=\"500\"\n    />\n  </div>\n</template>","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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`.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.1.0"},{"fix":"Set the `imageResourcesPath` prop to the correct URL or path with a trailing slash where the annotation layer icons are accessible.","message":"The `imageResourcesPath` prop might need to be configured if icons for the annotation layer are not loading correctly, especially in non-standard deployment environments.","severity":"gotcha","affected_versions":">=2.0.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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'`.","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.","error":"Failed to resolve import \"vue-pdf-embed\" from \"src/App.vue\". Does the file exist?"},{"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.","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.","error":"TypeError: Cannot read properties of null (reading 'style')"},{"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.","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.","error":"Worker src not set. See GlobalWorkerOptions.workerSrc"},{"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.","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.","error":"Error: Unknown or unsupported PDF format."}],"ecosystem":"npm"}