pdfobject

library2.3.1jsnpmunverified

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.

web-framework data

npm install pdfobject

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PDFOBJECT

pdfobject

web-frameworkjavascriptv2.3.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PDFObject

✓ import PDFObject from 'pdfobject'

✗ const PDFObject = require('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

✓ PDFObject.embed(url, targetElement, options)

✗ new PDFObject(url).embed(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

✓ if (PDFObject.supportsPDFs) { /* ... */ }

✗ if (PDFObject.isSupported) { /* ... */ }

Use `supportsPDFs` for feature detection to determine if the current browser and environment can embed PDFs inline.

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>  <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>

Debug

Known issues

breakingVersion 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.

affects: >=2.3.0

deprecatedAs 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.

affects: >=2.3.0

gotchaPDFObject 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.

affects: >=2.3.0

gotchaPDFObject 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.

affects: >=2.3.0

gotchaWhen 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.

affects: <2.3.1

Errors

Common errors & fixes

PDF not displaying on my mobile phone/tablet.

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.

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.

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'.

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' });`

Upgrade

Version history

2.3.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/pipwerks/PDFObject ↗

packagehttps://www.npmjs.com/package/pdfobject ↗

homepagehttps://pdfobject.com ↗