PDFObject

An open-source standards-friendly JavaScript utility for embedding PDF files into HTML documents.

Visit this project on Github

Note to PDFObject 1.x users: PDFObject 2.0 introduces breaking changes and is NOT backwards-compatible with PDFObject 1.x.

Browser support: PDFObject 2.0 is designed for modern browsers, and has been successfully tested in Chrome, Firefox, Safari (OS X and iOS), IE 9-11, and MS Edge. If you find issues or would like to share your own testing results, please post an issue in GitHub.

1. Create a container to hold your PDF

<div id="example1"></div>

2. Tell PDFObject which PDF to embed, and where to embed it

<script src="/js/pdfobject.js"></script>
<script>PDFObject.embed("/pdf/sample-3pp.pdf", "#example1");</script>

3. You can optionally use CSS to specify visual styling, including dimensions, border, margins, etc.

<style>
.pdfobject-container { height: 500px;}
.pdfobject { border: 1px solid #666; }
</style>

Question: Is JavaScript required for embedding PDFs in your HTML page?

Answer: No.

Why use PDFObject?

PDFObject 2.0 detects browser support for inline/embedded PDFs. (In case you were wondering, your browser embedded PDFs. )

If you're working with dynamic HTML, such as a single-page web app, you may need to insert PDFs on-the-fly. However, PDF embedding is not supported by certain browsers. If you insert markup without first checking for PDF support, you could wind up with missing content or a broken UI.

The PDFObject utility helps you avoid these situations by detecting support for PDF embedding in the browser; if embedding is supported, the PDF is embedded.

By default, PDFObject 2.0 inserts a fallback link to the PDF when the browser does not support inline PDFs. This ensures your users always have access to your PDF, and is designed to help you write less code. The fallback link can be customized, of the option can be disabled if you prefer.

PDFObject 2.0 is npm-ready. Modern web apps use npm to manage packages and dependencies. PDFObject 2.0 is registered with Node Package Manager (npm) and can be loaded dynamically.

PDFObject also makes it easy to specify Adobe's proprietary "PDF Open Parameters". (Be warned these parameters are only supported by Adobe Reader, most PDF readers will ignore the parameters, including the built-in PDF readers in Chrome, Internet Explorer, and Safari. Read more below.)

What PDFObject doesn't do

PDFObject is not a rendering engine. PDFObject just writes an <embed> element to the page, and relies on the browser or browser plugins to render the PDF. If the browser does not support embedded PDFs, PDFObject is not capable of forcing the browser to render the PDF.

If you need to force browsers to display a PDF, we suggest using PDF.js. Note that PDF.js is subject to its own limitations, such as cross-domain security restrictions. PDFObject and PDF.js play well together, there are links to some great PDF.js examples in the Examples section below.

PDFObject does not validate the existence of the PDF, or that the PDF is actually rendered. The assumption is that you are specifying a valid URL and the network is functioning normally. PDFObject does not check for 404 errors, and JavaScript cannot detect whether the PDF actually renders, unless you are using PDF.js, which is outside the scope of PDFObject.

PDFObject does not magically implement PDF Open Parameters. As mentioned above, these parameters are not widely support. The PDF rendering engine either supports them or doesn't — PDFObject cannot force the rendering engine to implement these features.

^ Back to top

API

PDFObject provides two properties and one method.

PDFObject.supportsPDFs [property]

Returns true or false based on detection of navigator.mimeTypes['application/pdf'] and/or ActiveX AcroPDF.PDF or PDF.PdfCtrl.

PDFObject does not perform detection for specific vendors (Adobe Reader, FoxIt, PDF.js, etc.). Note: For those who wish to target PDF.js, there is an option in PDFObject.embed() to force use of PDF.js. Read below for more details.

if(PDFObject.supportsPDFs){
   console.log("Yay, this browser supports inline PDFs.");
} else {
   console.log("Boo, inline PDFs are not supported by this browser");
}

Demo: Detection of PDF support

PDFObject.pdfobjectversion [property]

Returns the version of PDFObject.

console.log(PDFObject.pdfobjectversion); //"2.0.20160402"

PDFObject.embed(url [string], target [mixed], options [object]) [method]

Returns the embedded element (<embed> for most situations, and <iframe> when integrated with PDF.js), or false if unable to embed.

The heart of PDFObject, the embed method provides a ton of functionality and flexibility. See Examples for specific code examples and functioning demos.

//embeds a PDF and makes it fill the browser window
PDFObject.embed("myfile.pdf");
//embeds a PDF into the element "my-container" with no extra options specified
PDFObject.embed("myfile.pdf", "#my-container");
//embeds a PDF into the element "my-container" with a few options specified
var options = {
    height: "400px",
    pdfOpenParams: { view: 'FitV', page: '2' }
};
PDFObject.embed("myfile.pdf", "#my-container", options); 

 

Specifying a target HTML node

The target parameter can accept a CSS selector, HTML node, or jQuery object.

//passes a CSS selector to specify the target
PDFObject.embed("myfile.pdf", "#my-container");
//passes a vanilla HTML node for target
var mynode = document.getElementById("someID");
PDFObject.embed("myfile.pdf", mynode);
//passes a jQuery object (HTML node) for target
var $node = $("#someID");
PDFObject.embed("myfile.pdf", $node);

 

Options

The options parameter provides a lot of flexibility.

  • page [string or number]. Default: null

    Alias for PDF Open Parameters "page" option. Any number entered here will cause the PDF be opened to the specified page number (if the browser supports it). If left unspecified, the PDF will open on page 1.

    PDFObject.embed("myfile.pdf", "#my-container", {page: "2"});
  • id [string]. Default: null

    Any string entered here will be appended to the generated <embed> element as the ID. If left unspecified, no ID will be appended.

    PDFObject.embed("myfile.pdf", "#my-container", {id: "myID"});
    //outputs <embed src="myfile.pdf" id="myID">
  • width [string]. Default: "100%"

    Will insert the width as an inline style via the style attribute on the <embed> element. If left unspecified, PDFObject will default to 100%. Is standard CSS, supports all units, including px, %, em, and rem.

    Tip: It's safer to specify dimensions using CSS. See "Specifying dimensions" below.

    PDFObject.embed("myfile.pdf", "#my-container", {width: "500px"});
    //outputs <embed src="myfile.pdf" style="width:500px;">
  • height [string]. Default: "100%"

    Will insert the height as an inline style via the style attribute on the target element. If left unspecified, PDFObject will default to 100%. Is standard CSS, supports all units, including px, %, em, and rem.

    Tip: It's safer to specify dimensions using CSS. See "Specifying dimensions" below.

    PDFObject.embed("myfile.pdf", "#my-container", {height: "20rem"});
    //outputs <embed src="myfile.pdf" style="height:20rem;">
  • fallbackLink [string] or [boolean]. Default: "<p>This browser does not support inline PDFs. Please download the PDF to view it: <a href='[url]'>Download PDF</a></p>"

    Any string entered here will be inserted into the target element when the browser doesn't support inline PDFs.

    • HTML is supported
    • Use the shortcode [url] to insert the URL of the PDF (as specified via the URL parameter in the embed() method).
      var options = {
         fallbackLink: "<p>This is a <a href='[url]'>fallback link</a></p>"
      };
      PDFObject.embed("myfile.pdf", "#my-container", options);
      //If browser doesn't support inline PDFs, outputs:
      //<p>This is a <a href='myfile.pdf'>fallback link</a></p>
    • Entering false will disable the fallback text option and prevent PDFObject from inserting fallback text
      PDFObject.embed("myfile.pdf", "#my-container", {fallbackLink: false});
      //If browser doesn't support inline PDFs, outputs nothing
  • pdfOpenParams [object]. Default: null

    Allows you to specify Adobe's PDF Open Parameters.

    Warning: These are proprietary and not well supported outside of Adobe products. Most PDF readers support the page parameter, but not much else. PDF.js supports page, zoom, nameddest, and pagemode.

    • page is the most widely-supported PDF Open Parameter outside of Adobe products.
      PDFObject.embed("myfile.pdf", "#my-container", {pdfOpenParams: { page: 10 }});
      //If supported, will cause the PDF viewer to load
      //the PDF and automatically scroll to page 10
      Note that PDFObject provides a convenient alias for page so you don't need to use the pdfOpenParams child object. All other PDF Open Parameters need to be listed as children of the pdfOpenParams object, as illustrated above.
      PDFObject.embed("myfile.pdf", "#my-container", { page: 10 });
      //If supported, will cause the PDF viewer to load
      //the PDF and automatically scroll to page 10
    • Learn more about Adobe's PDF Open Parameters
    • Learn more about PDF.js's implementation of PDF Open Parameters
  • PDFJS_URL [string]. Default: null

    If you would like to use PDF.js with PDFObject, you will need to specify the URL of the PDF.js viewer HTML file. PDFObject will automatically append the required querystring to the PDF.js viewer HTML file URL. See the Examples section below for a functioning demo.

  • forcePDFJS [boolean]. Default: false

    If this boolean is set to true and the PDFJS_URL string is not null, PDFObject will attempt to use PDF.js to embed the PDF in the browser, regardless of the browser's default PDF viewer.

^ Back to top

Getting Started

Here are some of the most common use cases for PDFObject. See the Examples section below for more examples.

Default behavior: the full-browser embed

PDFObject.embed("/pdf/sample-3pp.pdf");
PDFObject.embed("/pdf/sample-3pp.pdf", document.body);

If you don't specify a target element, PDFObject will default to document.body, which will cause the PDF to fill the entire browser window.

The two examples here have identical functionality.

Demo: Full-browser embed (no selector specified)

Demo: Full-browser embed (explicit selector)

Specifying Dimensions

PDFObject.embed("myfile.pdf", "#my-container");
//outputs <embed src="myfile.pdf" style="width:100%;height:100%">

By default, PDFObject generates an <embed> element with a width and height of 100%. It will automatically fill the target container.

var options = {
   width: "20rem",
   height: "20rem"
};
PDFObject.embed("myfile.pdf", "#my-container", options);
//outputs <embed src="myfile.pdf" style="width:20rem;height:20rem">

PDFObject allows you to specify dimensions via the options parameter. These dimensions will be appended directly to the <embed> element, as shown here.

<style>
/* Only resize the element if PDF is embedded */
.pdfobject-container {
   width: 200px;
   height: 500px;
}
</style>

<div id="my-container"></div>

<script>
PDFObject.embed("myfile.pdf", "#my-container");
</script>

If you specify dimensions on the <embed> element directly, you will lose the ability to resize the element via CSS, because the inline styles will always take precedence over the other styles in your file. Therefore it is recommended that you specify dimensions using external CSS rules, as shown here.

Note: PDFObject automatically appends the class pdfobject to the <embed> element, and pdfobject-container to the target element. This helps you target your element in CSS.

In this example, the dimensions of the target element are only specified if the PDF has been embedded (via the pdfobject-container class).

Demo: Embed a PDF and specify dimensions using CSS

Page number specified

var options = {
    page: "2"
};
PDFObject.embed("/pdf/sample-3pp.pdf", "#my-container", options);

As previously mentioned, most PDF Open Parameters are not widely supported. However, there is one parameter that enjoys wide support: the page parameter.

If you specify a page number using the page parameter, as shown in this example, the PDF will auto-scroll to the specified page number.

Additional PDF Open Parameters specified

var options = {
    height: "400px",
    page: '2',
    pdfOpenParams: {
        view: 'FitV',
        pagemode: 'thumbs',
        search: 'lorem ipsum'
    }
};

PDFObject.embed("/pdf/sample-3pp.pdf", "#my-container", options);

As previously mentioned, most PDF Open Parameters are not widely supported. However, there is one parameter that enjoys wide support: the page parameter.

If you specify a page number using the page parameter, as shown in this example, the PDF will auto-scroll to the specified page number.

^ Back to top

Examples

The following links demonstrate the many ways PDFObject can be utilized.