{"id":11538,"library":"pdfobject","title":"PDFObject: PDF Embedding Utility","description":"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.","status":"active","version":"2.3.1","language":"javascript","source_language":"en","source_url":"https://pipwerks@github.com/pipwerks/PDFObject","tags":["javascript","pdf","pdfobject"],"install":[{"cmd":"npm install pdfobject","lang":"bash","label":"npm"},{"cmd":"yarn add pdfobject","lang":"bash","label":"yarn"},{"cmd":"pnpm add pdfobject","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"When using ESM in a browser environment, PDFObject exports itself as a default. For direct script tags, it populates a global `PDFObject` variable.","wrong":"const PDFObject = require('pdfobject')","symbol":"PDFObject","correct":"import PDFObject from 'pdfobject'"},{"note":"The primary API is the static `embed` method on the `PDFObject` global/import. It's not a class to be instantiated with `new`.","wrong":"new PDFObject(url).embed(targetElement, options)","symbol":"PDFObject.embed","correct":"PDFObject.embed(url, targetElement, options)"},{"note":"Use `supportsPDFs` for feature detection to determine if the current browser and environment can embed PDFs inline.","wrong":"if (PDFObject.isSupported) { /* ... */ }","symbol":"PDFObject.supportsPDFs","correct":"if (PDFObject.supportsPDFs) { /* ... */ }"}],"quickstart":{"code":"<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"UTF-8\">\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n    <title>PDFObject Quickstart</title>\n    <style>\n        #pdf-container {\n            width: 800px;\n            height: 600px;\n            border: 1px solid #ccc;\n            margin: 20px auto;\n        }\n    </style>\n</head>\n<body>\n    <h1>Embedding a PDF with PDFObject</h1>\n    <div id=\"pdf-container\"></div>\n\n    <!-- Load PDFObject from a CDN -->\n    <script src=\"https://unpkg.com/pdfobject/pdfobject.min.js\"></script>\n    <script>\n        // Replace with your actual PDF URL\n        const pdfUrl = 'https://pdfobject.com/pdf/sample.pdf'; \n\n        // Check if PDFObject is available and embedding is supported\n        if(PDFObject.supportsPDFs) {\n            PDFObject.embed(pdfUrl, \"#pdf-container\", {\n                height: \"100%\", // Make it fill the container\n                width: \"100%\",\n                id: \"my-embedded-pdf\",\n                // Example PDF Open Parameters (e.g., open to page 2, fit view)\n                pdfOpenParams: {\n                    view: \"FitV\",\n                    page: \"2\"\n                },\n                // Fallback content for browsers that don't support inline PDFs\n                fallbackLink: `<p>This browser does not support inline PDFs. You can <a href=\"${pdfUrl}\">download the PDF</a> instead.</p>`\n            });\n            console.log(\"PDF embedded successfully!\");\n        } else {\n            // Display fallback content if embedding is not supported\n            document.getElementById(\"pdf-container\").innerHTML = `<p>Your browser does not support inline PDFs. You can <a href=\"${pdfUrl}\">download the PDF</a> instead.</p>`;\n            console.warn(\"PDF embedding not supported in this browser.\");\n        }\n    </script>\n</body>\n</html>","lang":"javascript","description":"Demonstrates how to embed a PDF directly into an HTML element using PDFObject's `embed` method, including feature detection and fallback content."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.3.0"},{"fix":"Remove deprecated options from your `PDFObject.embed()` calls. They will be safely ignored but serve no function.","message":"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`.","severity":"deprecated","affected_versions":">=2.3.0"},{"fix":"Design your fallback content appropriately for mobile users, such as a download link. Do not expect inline PDF display on phones or tablets.","message":"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`.","severity":"gotcha","affected_versions":">=2.3.0"},{"fix":"Ensure your application handles the fallback scenario gracefully, providing clear instructions or a download option for users with disabled PDF viewers.","message":"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.","severity":"gotcha","affected_versions":">=2.3.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.3.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Most mobile browsers do not support inline PDF embedding, and PDFObject explicitly disables it for mobile devices since v2.3.","error":"PDF not displaying on my mobile phone/tablet."},{"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.","cause":"These options were deprecated and removed in PDFObject v2.3.0 due to a re-architecting of PDF detection and embedding logic.","error":"My `forceIframe` or `assumptionMode` options are being ignored and don't seem to work."},{"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' }`.","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.","error":"PDF is embedded, but it doesn't open to the specified page number or view settings."},{"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' });`","cause":"In versions prior to 2.3.1, the filename for downloaded base64 PDFs in fallback scenarios was hardcoded.","error":"When embedding a base64 PDF and the browser falls back to downloading, the file is always named 'file.pdf'."}],"ecosystem":"npm"}