PDFObject
Question: Is JavaScript required for embedding PDFs in your HTML page?
Answer: No.
In fact, here are some examples for embedding PDFs in your web page using pure HTML markup without JavaScript, if you'd rather go that route.
Why use PDFObject?
PDFObject 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. If embedding is NOT supported by the browser, the PDF will NOT be embedded.
By default, PDFObject 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, or the option can be disabled if you prefer.
PDFObject is npm-ready. Modern web apps use npm to manage packages and dependencies. PDFObject 2.x 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, Edge, Internet Explorer, and Safari. Read more below.
What PDFObject doesn't do
PDFObject is not a rendering engine. PDFObject just writes an 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 Mozilla's www.cronistalascolonias.com.ar Note that www.cronistalascolonias.com.ar is subject to its own limitations, such as cross-domain security restrictions. PDFObject and www.cronistalascolonias.com.ar play well together, there are links to some great www.cronistalascolonias.com.ar examples in the Examples section below.
PDFObject does not provide the ability to customize the look and feel of the PDF toolbar. The toolbar is controlled by the browser, and will vary widely from browser to browser (Chrome versus Safari versus Firefox, etc.). Some of these browsers provide the ability to show or hide the toolbar, or a feature such as the search field, via PDF Open Parmeters. However, in general the browsers do NOT provide any mechanism for customizing the toolbar. If you really need to customize the toolbar, try forking Mozilla's www.cronistalascolonias.com.ar and customizing it to suit your needs.
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 errors, and JavaScript cannot detect whether the PDF actually renders, unless you are using www.cronistalascolonias.com.ar, which is outside the scope of PDFObject.
PDFObject does not magically implement PDF Open Parameters. As mentioned above, these parameters are not widely supported. The PDF rendering engine either supports them or doesn't — PDFObject cannot force the rendering engine to implement these features.
Back to top
Browser Support
PDFObject 2.x is designed for modern browsers, and has been successfully tested in Chrome, Firefox, Safari, IE 11, and MS Edge. Mobile browsers do not support PDF embedding! For mobile browsers (Android, iOS, iPadOS), PDFObject will load your specified fallback content. If you find issues or would like to share your own testing results, please post an issue in GitHub.
IMPORTANT: Browser support for PDFObject does not mean the browser supports PDF embedding! The reason PDFObject exists is to help you embed PDFs when the browser supports PDFs, and to display alternative non-PDF content when the browser doesn't support PDFs. While most modern desktop browsers support PDF embedding, some do not. Most notably, Internet Explorer 11 requires a 3rd-party tool such as Adobe Acrobat for displaying PDFs.
Back to top
API
PDFObject provides two properties and one method.
[property]
Returns or based on detection of and/or ActiveX or .
Will return for all mobile browsers. With the advent of in and greater, now returns for all modern desktop browsers.
PDFObject does not perform detection for specific vendors (Adobe Reader, FoxIt, www.cronistalascolonias.com.ar, etc.). Note: For those who wish to target www.cronistalascolonias.com.ar, there is an option in to force use of www.cronistalascolonias.com.ar Read below for more details.
Demo: Detection of PDF support
[property]
Returns the version of PDFObject.
[method]
Returns the embedded element ( or depending on situation), or if unable to embed.
See Examples for specific code examples and functioning demos.
Specifying a target HTML node
The parameter can accept a CSS selector, HTML node, or jQuery object.
Options
The parameter provides a lot of flexibility.
assumptionMode [boolean]. Default:
Older browsers require third-party plugins such as Adobe Reader for displaying PDFs. Most newer 'modern' browsers provide PDF support natively, and no longer require plugins. When PDFObject's is set to , PDFObject will check to see if the browser is considered modern. If yes, PDFObject will assume PDF support is available, will bypass its normal PDF support detection, and will write the PDF embed code to the page. Browsers that are not considered modern will fall back to the default PDFObject behavior — a check will be performed to see if PDF embedding is supported before attempting to insert the PDF embed code. If PDF support is detected, the embed will proceed. If not, the normal fallback behavior will apply.
is a direct response to Mozilla's decision to remove support in Firefox. Mozilla is attempting to make Firefox more secure by reducing opportunities for browser fingerprinting. Plugin inspection is a core component of many browser fingerprinting techniques. However, many well-intentioned scripts such as PDFObject query to determine whether specific media, such as PDFs (), Flash SWFs, and specific audio or video codecs are supported.
fallbackLink [string] or [boolean]. Default:
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 to insert the URL of the PDF (as specified via the URL parameter in the method).
- Entering will disable the fallback text option and prevent PDFObject from inserting fallback text
forceIframe [boolean]. Default:
If this boolean is set to , and PDF embedding is supported by the browser, PDFObject will write an to the page instead of an .
forcePDFJS [boolean]. Default:
If this boolean is set to and the string is not null, PDFObject will attempt to use www.cronistalascolonias.com.ar to embed the PDF in the browser, regardless of the browser's default PDF viewer.
height [string]. Default:
Will insert the height as an inline style via the attribute on the the generated element ( or depending on situation). If left unspecified, PDFObject will default to %. Is standard CSS, supports all units, including px, %, em, and rem.
If you would like PDFObject to omit all inline styles, set the option to .
Tip: It's safer to specify dimensions using non-inline CSS instead of this inline code. See "Specifying dimensions" below.
id [string]. Default:
Any string entered here will be appended to the generated or element as the ID. If left unspecified, no ID will be appended.
omitInlineStyles [boolean]. Default:
If this boolean is set to , PDFObject will not include any inline styles when generating the or elements.
Warning: If you do not specify your own styles, especially sizing, via CSS, the PDF may render incorrectly or be invisible.
page [string or number]. Default:
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.
PDFJS_URL [string]. Default:
If you would like to use www.cronistalascolonias.com.ar with PDFObject, you will need to specify the URL of the www.cronistalascolonias.com.ar viewer HTML file. PDFObject will automatically append the required querystring to the www.cronistalascolonias.com.ar viewer HTML file URL. See the Examples section below for a functioning demo.
pdfOpenParams [object]. Default:
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 parameter, but not much else. www.cronistalascolonias.com.ar supports , , , and .
- is the most widely-supported PDF Open Parameter outside of Adobe products. Note that PDFObject provides a convenient alias for so you don't need to use the child object. All other PDF Open Parameters need to be listed as children of the object, as illustrated above.
- Learn more about Adobe's PDF Open Parameters
- Learn more about www.cronistalascolonias.com.ar's implementation of PDF Open Parameters
supportRedirect [boolean]. Default:
On macOS systems, Safari does not properly embed PDFs that have been requested via URL redirection when embedding using the element. Setting to forces PDFObject to use an instead of an for desktop Safari.
Hat tip to John Hunter for the discovery and fix.
suppressConsole [boolean]. Default:
If this boolean is set to , PDFObject not write any error messages to the browser's console.
width [string]. Default:
Will insert the width as an inline style via the attribute on the generated element ( or depending on situation). If left unspecified, PDFObject will default to %. Is standard CSS, supports all units, including px, %, em, and rem.
If you would like PDFObject to omit all inline styles, set the option to .
Tip: It's safer to specify dimensions using non-inline CSS instead of this inline code. See "Specifying dimensions" below.
Back to top
Common Use Cases
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
Embedding in a sized container
Demo: Embed a PDF and specify dimensions using CSS
Page number specified
Additional PDF Open Parameters specified
Demo: Specifying PDF URL containing querystring, with PDF Open Parameters
Back to top
Examples
The following links demonstrate the many ways PDFObject can be utilized.
Back to top
Changelog
- , October : Reinstated check for to play nice with React and NextJS.
- , September : Version bump for NPM. Sigh.
- , September : Fixed typo affecting `suppressConsole` functionality. Hat tip to John Hunter for the discovery and fix.
- , September : Fixed typo affecting styling of iframe when forcing PDFJS.
- , September :
- New behavior: Dropping support for IE9 and IE10, which have practically 0 marketshare now.
- New behavior: Now explicitly displaying fallback content for all mobile devices, even "Request Desktop" version of pages in iOS. The reasoning is simple: As the time of this update, no mobile device (Android, iOS) natively supports embedded PDFs. This change will lead to a consistent experience across all mobile devices. PDFs can be rendered via www.cronistalascolonias.com.ar on mobile if embedding on mobile is a critical need. www.cronistalascolonias.com.ar is not included with PDFObject.
- New option: Omit inline styles by setting option to . This helps developers who use strict environments where inline styles are not allowed. Note you will be responsible for applying proper styling via your own CSS.
- New option: Suppress console logging by setting option to . PDFObject currently places error messages in the console if the PDF can't be embedded for some reason. This option allows you to mute those alerts.
- New option: Force PDFObject to embed the PDF in an iframe (instead of an ) by setting to .
- New option: On macOS systems, Safari does not properly embed PDFs that have been requested via URL redirection when embedding using the element. Setting to forces PDFObject to use an instead of an for desktop Safari. Hat tip to John Hunter for the discovery and fix.
- Refactored to use more modern code conventions, such as in lieu of , in place of , and in place of . Implemented a declaration before each variable instead of the Crockford practice of one per function.
- Refactored to make code safer for server-side www.cronistalascolonias.com.ar-based environments.
- Refactored to eliminate string-based element creation via . Replaced with standard DOM methods. This helps alleviate unforeseen issues with file names. Only exception is insertion of fallback content, which is passed as a string via .
- Removed iframe scrollfix for iOS, as it is no longer needed as of iOS iOS 12 and lower have ~% marketshare and shrinking fast.
- Refactored codebase to make it more concise and legible.
- , October : Changed handling of iOS to reflect Safari's lack of support for embedding inline PDFs. (In iOS, Safari will only display an image preview of the first page of a PDF, and will not render other pages of the PDF.) Other iOS web browsers use Apple's native WebView to render pages, which leads to the same limitations as Safari. Therefore, PDFObject now assumes any iOS-based web browsers will not support PDF embedding.
- , October : Changed default from to . This will ensure PDFObject 2.x will work for Firefox users without requiring them to change their codebase to enable . All they need to do is load the latest version of PDFObject, the PDFObject utility will take care of the rest.
- (dev branch), January : Modified to support Mozilla's removal of inspection. Added for manual override of PDFObject's default sniffing.
- , April : Initial release of PDFObject Contains breaking changes, and is not compatible with PDFObject 1.x.
-
-