Wrapping the default PDF.js viewer as a web component

[alekswebnet]

Hi PDF.js team and community 👋

While integrating PDF.js into a modern web application stack, I found that many developers struggle with embedding the full viewer in component-based frameworks (Vue, React, etc.). The official viewer works great as a standalone application, but integrating it cleanly into SPA architectures can require quite a bit of setup.

To simplify this, I created a small wrapper project called pdfjs-viewer-element that exposes the PDF.js viewer as a Web Component.

The idea is to provide a simple integration layer so developers can use the viewer like this:

<pdfjs-viewer-element src="/example.pdf"></pdfjs-viewer-element>

Internally it loads the official viewer and manages the iframe/worker setup.

I want to emphasize that:

• this project does not modify PDF.js itself
• it simply wraps the existing viewer
• the goal is to make integration easier in modern frontend environments
• you have possibility to restyle default viewer by injecting CSS inside the component

Repository:
https://github.com/alekswebnet/pdfjs-viewer-element

Before promoting this approach more widely, I wanted to ask the maintainers and community:

1. Does exposing the viewer via a Web Component seem like a reasonable integration approach?
2. Are there any architectural pitfalls I should be aware of when embedding the viewer this way?
3. Would you recommend a different integration strategy for SPA environments?

Any feedback would be very valuable. My goal is to make PDF.js easier to adopt without going against the intended usage patterns.

Thanks for the amazing project and all the work you put into it.

[Snuffleupagus]

Please note that we explicitly ask users not to utilize the viewer as-is, to avoid custom deployments being mistaken for the built-in Firefox PDF Viewer since that causes end-user confusion and "incorrect" bug reports against the PDF.js project; as mentioned in http://mozilla.github.io/pdf.js/getting_started/#introduction (emphasis mine):

The viewer is built on the display layer and is the UI for PDF viewer in Firefox and the other browser extensions within the project. It can be a good starting point for building your own viewer. However, we do ask if you plan to embed the viewer in your own site, that it not just be an unmodified version. Please re-skin it or build upon it.

[alekswebnet]

Thanks for the clarification — understood.

To align with that guidance, I guess I have 2 options:

First

• Position the component as a packaging/convenience layer + starting point for building a custom viewer, where re-skinning is expected
• Update the README to clearly state that unmodified deployments are discouraged because they can be mistaken for Firefox’s built-in PDF Viewer and generate incorrect bug reports
• Add “Reskin/Customize” section with recommended minimal changes that visibly differentiate the UI (branding/colors/icons/title, etc.) and disable/replace PDF.js branding where appropriate.

Second

• Reskin component by default so it's not recognized as PDF.js default viewer.
• Add “Reskin/Customize” section to give guidance for others.

Questions:

• What option would you prefer?
• Is there a suggested minimal set of UI changes you consider sufficient to avoid end-user confusion?

[alekswebnet]

I created an issue in the pdfjs-viewer-element repository to address this problem, if anyone is interested: missing-elements/pdfjs-viewer#47.