PDFObject: PDF Embedding Utility

2.3.1 · active · verified Sun Apr 19

PDFObject is a lightweight JavaScript utility designed for embedding PDF documents directly into HTML pages. Currently at version 2.3.1, it provides a robust solution for displaying PDFs inline across various browsers. The project maintains a steady release cadence, with significant updates (like 2.3) introducing major architectural changes approximately annually, alongside minor patches for fixes and enhancements. A key differentiator is its shift to a pure `<iframe>` approach in v2.3, abandoning the less consistent `<embed>` element, which enhances cross-browser compatibility and reliability. It also intelligently leverages `navigator.pdfViewerEnabled` to determine native PDF viewing capabilities and automatically falls back to download options on unsupported platforms, especially mobile devices. This makes it a pragmatic choice for integrating PDF content without external plugins.

Common errors

```
PDF not displaying on my mobile phone/tablet.
```
cause Most mobile browsers do not support inline PDF embedding, and PDFObject explicitly disables it for mobile devices since v2.3.

fix PDFObject's design anticipates this and provides fallback content. Ensure you have `fallbackLink` or `fallbackContent` configured for unsupported scenarios. Users will be prompted to download the PDF instead.
```
My `forceIframe` or `assumptionMode` options are being ignored and don't seem to work.
```
cause These options were deprecated and removed in PDFObject v2.3.0 due to a re-architecting of PDF detection and embedding logic.

fix Remove these deprecated options from your `PDFObject.embed()` calls. The library now defaults to an `<iframe>` and handles detection automatically, rendering these options unnecessary.
```
PDF is embedded, but it doesn't open to the specified page number or view settings.
```
cause Prior to v2.2.9, there was a regression in how `pdfOpenParams` were handled, specifically affecting sequencing and ensuring parameters like `page` were correctly applied with others.

fix Upgrade to PDFObject v2.2.9 or higher. Ensure your `pdfOpenParams` are correctly formatted according to Adobe's PDF Open Parameters specification, e.g., `{ page: '2', view: 'FitV' }`.
```
When embedding a base64 PDF and the browser falls back to downloading, the file is always named 'file.pdf'.
```
cause In versions prior to 2.3.1, the filename for downloaded base64 PDFs in fallback scenarios was hardcoded.

fix Upgrade to PDFObject v2.3.1 or later. Use the `fallbackFileNameForBase64` option in your `PDFObject.embed()` call to specify the desired filename, for example: `PDFObject.embed(base64Data, '#container', { fallbackFileNameForBase64: 'MyDocument.pdf' });`

Warnings

breaking Version 2.3 removed the use of the `<embed>` HTML element in favor of a pure `<iframe>` approach. This improves compatibility and robustness, but may require adjustments if your CSS or JavaScript explicitly targeted `<embed>` elements created by PDFObject.
Fix: Ensure your CSS and JavaScript targeting embedded PDFs uses `iframe` selectors instead of `embed`. The `id` option for the embedded element remains supported for targeting.
deprecated As of v2.3, several options have been deprecated due to the architectural shift to `<iframe>` and improved PDF detection logic. These include `assumptionMode`, `forceIframe`, and `supportRedirect`.
Fix: Remove deprecated options from your `PDFObject.embed()` calls. They will be safely ignored but serve no function.
gotcha PDFObject automatically assumes that mobile devices do not support inline PDF embedding (as of February 2024, no mobile browsers properly support it). It will present fallback content on mobile regardless of `navigator.pdfViewerEnabled`.
Fix: Design your fallback content appropriately for mobile users, such as a download link. Do not expect inline PDF display on phones or tablets.
gotcha PDFObject relies on `navigator.pdfViewerEnabled` (if available and enabled) to detect native PDF support. If a user has intentionally disabled PDF viewing in their browser settings, PDFObject will respect this and present fallback content.
Fix: Ensure your application handles the fallback scenario gracefully, providing clear instructions or a download option for users with disabled PDF viewers.
gotcha When embedding base64 PDFs, if the browser does not support inline embedding and a download fallback occurs, the filename was hardcoded to 'file.pdf' in versions prior to 2.3.1.
Fix: Upgrade to PDFObject v2.3.1 or higher and use the new `fallbackFileNameForBase64` option to specify a custom filename for downloaded base64 PDFs when inline embedding fails.

Install

npm install pdfobject npm
yarn add pdfobject yarn
pnpm add pdfobject pnpm

Imports

PDFObject
wrong:
```
const PDFObject = require('pdfobject')
```
correct:
```
import PDFObject from 'pdfobject'
```
When using ESM in a browser environment, PDFObject exports itself as a default. For direct script tags, it populates a global `PDFObject` variable.
PDFObject.embed
wrong:
```
new PDFObject(url).embed(targetElement, options)
```
correct:
```
PDFObject.embed(url, targetElement, options)
```
The primary API is the static `embed` method on the `PDFObject` global/import. It's not a class to be instantiated with `new`.
PDFObject.supportsPDFs
wrong:
```
if (PDFObject.isSupported) { /* ... */ }
```
correct:
```
if (PDFObject.supportsPDFs) { /* ... */ }
```
Use `supportsPDFs` for feature detection to determine if the current browser and environment can embed PDFs inline.

Quickstart

Demonstrates how to embed a PDF directly into an HTML element using PDFObject's `embed` method, including feature detection and fallback content.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>PDFObject Quickstart</title>
    <style>
        #pdf-container {
            width: 800px;
            height: 600px;
            border: 1px solid #ccc;
            margin: 20px auto;
        }
    </style>
</head>
<body>
    <h1>Embedding a PDF with PDFObject</h1>
    <div id="pdf-container"></div>

    <!-- Load PDFObject from a CDN -->
    <script src="https://unpkg.com/pdfobject/pdfobject.min.js"></script>
    <script>
        // Replace with your actual PDF URL
        const pdfUrl = 'https://pdfobject.com/pdf/sample.pdf'; 

        // Check if PDFObject is available and embedding is supported
        if(PDFObject.supportsPDFs) {
            PDFObject.embed(pdfUrl, "#pdf-container", {
                height: "100%", // Make it fill the container
                width: "100%",
                id: "my-embedded-pdf",
                // Example PDF Open Parameters (e.g., open to page 2, fit view)
                pdfOpenParams: {
                    view: "FitV",
                    page: "2"
                },
                // Fallback content for browsers that don't support inline PDFs
                fallbackLink: `<p>This browser does not support inline PDFs. You can <a href="${pdfUrl}">download the PDF</a> instead.</p>`
            });
            console.log("PDF embedded successfully!");
        } else {
            // Display fallback content if embedding is not supported
            document.getElementById("pdf-container").innerHTML = `<p>Your browser does not support inline PDFs. You can <a href="${pdfUrl}">download the PDF</a> instead.</p>`;
            console.warn("PDF embedding not supported in this browser.");
        }
    </script>
</body>
</html>

view raw JSON →