Displaying PDFs in Vue 3 Applications

Embedding a PDF inside a Vue 3 SPA sounds straightforward—until you hit your first CORS error, discover the browser renders it differently on Safari, or realize your 200-page document is blocking the main thread. This article covers the three practical approaches developers actually use for displaying PDFs in Vue 3, with honest trade-offs for each.

The Three Core Approaches

1. Native Browser Embed: <iframe> or <embed>

The fastest way to get a PDF on screen is to hand it off to the browser’s built-in PDF renderer.

<template>
  <iframe
    :src="pdfUrl"
    width="100%"
    height="700px"
    style="border: none"
  />
</template>

<script setup lang="ts">
const pdfUrl = '/documents/report.pdf'
</script>

When it works well: Internal tools, admin dashboards, or any context where UI consistency isn’t critical and the PDF is served from the same origin.

The real limitations:

• Zero control over the toolbar, zoom controls, or theming
• Behavior varies across browsers—Chrome, Firefox, and Safari each render differently
• Mobile browsers often download the file instead of displaying it inline
• Loading state is invisible to your Vue component, so you can’t show a spinner or handle errors gracefully

If you’re loading a PDF from a different domain, the browser will block the request unless the server sends the correct Access-Control-Allow-Origin headers. A same-origin proxy endpoint on your backend is the cleanest fix.

2. PDF.js with Vue 3: Direct Integration

PDF.js is Mozilla’s open-source PDF rendering engine. As of the 5.x release series, it ships as an ESM-first package. You import from build/pdf.mjs and load a separate worker (pdf.worker.mjs) to keep rendering off the main thread.

npm install pdfjs-dist

<script setup lang="ts">
import { onMounted, ref } from 'vue'
import * as pdfjsLib from 'pdfjs-dist/build/pdf.mjs'

pdfjsLib.GlobalWorkerOptions.workerSrc = new URL(
  'pdfjs-dist/build/pdf.worker.mjs',
  import.meta.url
).toString()

const canvasRef = ref<HTMLCanvasElement | null>(null)

onMounted(async () => {
  const pdf = await pdfjsLib.getDocument('/documents/report.pdf').promise
  const page = await pdf.getPage(1)
  const viewport = page.getViewport({ scale: 1.5 })
  const canvas = canvasRef.value!
  const ctx = canvas.getContext('2d')!
  canvas.height = viewport.height
  canvas.width = viewport.width
  await page.render({ canvasContext: ctx, viewport }).promise
})
</script>

<template>
  <canvas ref="canvasRef" />
</template>

What you gain: Full control over rendering, page navigation, zoom, and theming. PDF.js supports standard annotations and AcroForm fields, though form and annotation behavior can depend on rendering configuration.

What you should know:

• The pdfjs-dist package adds a noticeable payload to your client bundle. Use dynamic import() to lazy-load it.
• XFA-based forms (common in older government PDFs) have limited support and may not render correctly.
• For large documents, PDF.js can fetch PDFs in chunks when the server supports HTTP range requests (Accept-Ranges: bytes), which can improve perceived performance for large files.
• Worker configuration is the most common setup issue in Vite projects. The new URL(..., import.meta.url) pattern shown above resolves the worker path correctly at build time.

3. Vue PDF Wrappers

Several maintained Vue 3 components wrap PDF.js and expose a simpler component API. vue-pdf-embed is one actively maintained option that handles worker setup, page rendering, and reactive prop updates for you.

<script setup lang="ts">
import VuePdfEmbed from 'vue-pdf-embed'
</script>

<template>
  <VuePdfEmbed source="/documents/report.pdf" />
</template>

The trade-off is less granular control in exchange for significantly less boilerplate. These wrappers are a good fit when you need a working Vue 3 PDF viewer quickly and don’t need to customize the rendering pipeline.

Note: Some older packages like vue3-pdf-app are no longer actively maintained. Evaluate any wrapper’s maintenance status and compatibility with modern bundlers like Vite before adopting it.

Choosing the Right Approach

Conclusion

For most Vue 3 applications, the decision is straightforward: use <iframe> for simple same-origin embeds, reach for a maintained Vue wrapper when you need a working viewer without much setup, and integrate PDF.js directly when you need full control over rendering, navigation, or performance for large documents. Whichever path you choose, configure the PDF.js worker correctly and lazy-load the library. Those two steps alone will prevent the most common issues developers run into when embedding PDFs in Vue apps.

FAQs

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.