DEV Community: Kittisak Ma

PDFium vs PDF.js: Choosing a React PDF Engine (2026)

Kittisak Ma — Tue, 18 Aug 2026 07:14:10 +0000

A few months ago, I opened an architecture layout in a PDF.js-based viewer. It loaded fine. Then I zoomed in, and the re-render lagged. Zoom out, lag again. The page held thousands of vector strokes, and every zoom step seemed to redraw all of them. That's the kind of thing that starts a PDFium vs PDF.js argument in your own head.

Chrome's built-in viewer renders with PDFium, so I opened the same file there to check whether the engine was the difference. It re-rendered smoothly. Later, while researching what PDFium can actually do in a browser, I came across EmbedPDF, which runs PDFium through WebAssembly, and tried the file in that too. Also smooth. That's when I started taking the engine question seriously. And as I dug in, I found the lag traced to viewer zoom strategy more than to the engine itself (more on that below).

Quick disclosure: I work on React PDF Kit, which runs on PDF.js. So I have a side, and that's exactly why I tested PDFium fairly before writing this. If anything, I've overcorrected in its favor.

Most content on this topic is either marketing from companies selling a PDFium-based SDK, or a 2014 benchmark of an early PDFium-to-JS port that beat PDF.js with the text layer switched off. There's no current take from a React developer's point of view. The belief that PDFium just renders better leans on Dropbox's 2017 migration writeup and vendor blog posts, with no neutral in-browser benchmark behind it.

So this isn't a horse race, it's an architecture decision. PDFium's strongest arguments come first here, so don't read the running order as a verdict. The one edge people reliably hand PDFium is color. It turns out PDF.js can match it, through color management that ships but sits off by default behind a setting almost nobody flips on. So PDFium's real advantage is narrower than its reputation: it gets color right with nothing to configure. PDF.js's clean wins are the text layer and bundle size. I'll show you what's verifiable and flag what you should prototype yourself.

What PDFium and PDF.js actually are

You probably know PDF.js already. It's Mozilla's JavaScript PDF renderer, and it parses and rasterizes PDFs in pure JavaScript onto an HTML5 canvas. Nearly every React PDF library sits on top of it: wojtekmaj/react-pdf, @anaralabs/lector, @mikecousins/react-pdf, the archived react-pdf-viewer (phuocng), and the one I work on, React PDF Kit. As of late July 2026, pdfjs-dist is at 6.1.200 (published June 27, 2026), with around 15M weekly npm downloads and 53K GitHub stars. It's the default substrate for React PDF work.

PDFium needs more of an intro, because most React devs have used it without knowing. It's Google's C++ PDF engine, originally Foxit's commercial SDK before Google open-sourced it, and it's the engine inside Chrome, Edge, and Android's PDF viewer. Every time you open a PDF in Chrome, that's PDFium doing the work. It's versioned by Chromium milestone, around 150.x right now, not by npm.

	PDF.js	PDFium
Maker	Mozilla	Google (originally Foxit)
Language	JavaScript	C++
License	Apache 2.0	BSD-3-Clause
Reaches the browser as	JavaScript plus a worker	a WebAssembly binary
Powers	Firefox's viewer	Chrome, Edge, Android viewers
Versioned by	pdfjs-dist on npm (6.1.200)	Chromium milestone (~150.x)

The catch is that PDFium is C++. To run in a browser it has to be compiled to WebAssembly. That one fact is the whole story: one engine is JavaScript that ships as JavaScript, the other is C++ that ships as a WASM binary. Most of the tradeoffs in this piece fall straight out of it.

The library landscape: which engine is under your viewer

Most of the time you don't pick an engine directly. You pick a React library, and it picks the engine. Here's the map.

Library	Engine	Notes
wojtekmaj/react-pdf	PDF.js	Rendering primitives, no built-in viewer UI
@anaralabs/lector	PDF.js	Headless viewer toolkit
@mikecousins/react-pdf	PDF.js	Lightweight hook-based viewer
react-pdf-viewer (phuocng)	PDF.js	Archived March 2026
React PDF Kit	PDF.js	`@react-pdf-kit/viewer` 2.7.1, on pdfjs-dist 5.4.530
EmbedPDF	PDFium (WASM)	by CloudPDF, 2.14.4, MIT

The PDF.js column is crowded because PDF.js is the default substrate for React PDF work. If you want a PDF.js alternative in React at the engine level, EmbedPDF is effectively the production-ready option today, with low-level wrappers like @embedpdf/pdfium and @hyzyla/pdfium underneath it.

Two caveats before you use that table. EmbedPDF is one PDFium-in-React viewer, not PDFium itself, so don't treat "embedpdf react" and "PDFium" as synonyms. And the commercial SDKs sit in their own tier. Nutrient (formerly PSPDFKit) actually runs a PDFium-derived fork, while Apryse (formerly PDFTron) runs its own engine, so "commercial means custom engine" is only half true. I couldn't confirm Syncfusion's engine lineage, so I left it out rather than guess.

For the full feature-by-feature comparison of the React libraries themselves, see our React PDF library comparison on the blog.

Rendering fidelity: fonts, color, and complex graphics

This is the number one reason a team looks at PDFium. It's the engine Chrome ships, so its output matches what users see when they open the file natively, and it tends to match Acrobat on the weird stuff. PDF.js does its parsing and font work in JavaScript, and that's where the gaps show up.

Color and CMYK

Start here, because it's the claim people are surest about, and the one that turns out to be backwards. A quick note on terms, since not everyone works in print. CMYK is the four-ink color model print uses, screens use RGB, and an ICC profile carries a document's instructions for how its colors should map between the two. The reputation says PDF.js can't manage color: it renders in RGB, ignores embedded ICC profiles, and converts CMYK through a rough built-in fallback. That stopped being true in 5.0, when PDF.js bundled QCMS, Mozilla's own color engine, as a WebAssembly module, together with a CGATS001 DeviceCMYK reference profile. That is real ICC color management. It's just off by default.

Two getDocument options switch it on. wasmUrl turns on the ICC path for embedded profiles, so ICCBased streams run through QCMS instead of the old alternate-colorspace fallback, the embedded-profile gap that issue #2856 tracked for years. iccUrl goes further and routes DeviceCMYK through an ICC transform against the CGATS001 profile rather than a polynomial approximation, which is the imperfect default conversion a Mozilla maintainer described in issue #8500. Both of those long-standing complaints describe the default path, and the ICC path is what closes them.

The gap is easy to measure and easy to see. Open a CMYK-heavy file in a stock PDF.js viewer next to Chrome's native one, and the colors are visibly off. On a DeviceCMYK swatch file, default PDF.js on 5.4.530 (the build tested here) is off from Chrome's PDFium by as much as 60 out of 255 on a single channel. Turn the ICC options on and the same build comes within 3 out of 255, down at the level of screenshot sampling noise. So the color difference people blame on the engine is really a config default, not an engine limit. For marketing collateral, print proofs, packaging, or spot-color design files, that drift is the kind of error that surfaces only when the printed piece comes back wrong. And the fix is a few lines of config.

PDFium's color story is narrower than its reputation too, and it's worth stating fairly. It matches Chrome because it is Chrome's engine, through an internal C++ CMYK-to-RGB path rather than app-layer color management. The browser viewers built on it pass that output straight through, so there's no separate ICC pipeline doing the work. What PDFium gives you is correct color with nothing to set up. That's a real convenience, but it's parity by default, not something PDF.js can't do.

Turning it on, and the trap

Setting wasmUrl and iccUrl does nothing on its own. The ICC path only activates when PDF.js is cleared to fetch worker assets, and that clearance turns on only if cMapUrl, standardFontDataUrl, and wasmUrl are all set and all resolve to valid fetch URLs against your document base. Leave out standardFontDataUrl and the color options are ignored in silence, no error, and no warning unless you've raised the verbosity level. A working call passes all of them:

pdfjsLib.getDocument({
  url,
  cMapUrl: '/pdfjs/cmaps/',
  standardFontDataUrl: '/pdfjs/standard_fonts/',
  wasmUrl: '/pdfjs/wasm/',
  iccUrl: '/pdfjs/iccs/',
})

One last catch: those paths resolve inside the worker (the background thread PDF.js does its parsing in), not on the page. A relative URL there is taken relative to the worker script, not your page, so it quietly points at the wrong place. Pass absolute URLs instead. None of this is documented, so you only find it by reading the source, and it's easy to get half-right. That is the real reason so few PDF.js viewers turn color management on, not any missing capability.

Fonts and CJK

PDF.js converts and sanitizes embedded fonts in JavaScript, which is where its edge cases live: missing glyphs in Source Han Sans (#5377), type3 font bugs (#19634), a CJK glyph regression (Bugzilla 1146106). If your documents are CJK-heavy, PDFium lands closer to Acrobat more often.

But most everyday PDFs render fine in PDF.js. Mozilla's own benchmark treats the badly-broken cases as unusual files. And not every difference is the engine's fault. Issue #19221 is a font error that also breaks in Adobe Reader, because the PDF itself is malformed.

The gap is a moving target

One more thing on fidelity, and it cuts against my own anchor. PDF.js 6.0 shipped on May 30, 2026, and it landed work in exactly the areas where PDFium historically led: CID and CJK font recovery, Adobe-parity hinting, and knockout and soft-mask transparency fixes. Those are the CJK and obscure-feature gaps, narrowing in a single release.

So the gap is real today, but it's a trajectory, not a constant. PDFium moves too, with every Chromium milestone, so "date your comparison" cuts both ways. The full v6 rendering story deserves its own write-up, and that one's coming.

Rendering performance on heavy and complex PDFs

The first question is usually which engine is faster. It depends on your documents, and I'll get to why the public evidence can't settle it. What you feel right away is how each one copes with a heavy document, and it doesn't take an exotic file. An ordinary layout-heavy PDF with many elements and text runs is enough to make any renderer sweat. Past that sit the hard cases: CAD and architectural exports with huge path-operator counts (PDF.js #14652), large-format pages with dense vector linework, files with many optional-content layers that cost parse time even when hidden, and multi-hundred-page scans.

Here's the correction to my own first take. I'd assumed PDF.js re-renders the canvas on every zoom step and therefore lags. That's an oversimplification. Zoom smoothness depends on the viewer's zoom strategy more than on the engine.

Some PDF.js viewers apply a cheap visual scale during the gesture and defer the sharp re-render until you let go, which feels smooth even on dense pages at the cost of a moment of blur. Others re-raster at every step, staying sharp throughout but lagging on complex documents. PDFium viewers pair native or WASM rasterization with virtual scrolling and tiling, which reads as responsive, but they pay the same cost re-rasterizing dense vector content at high zoom.

That's what I was actually seeing in my architecture layout. It painted fine, then lagged on every scale change in one PDF.js viewer. The same file zoomed smoothly in Chrome's native PDFium, in EmbedPDF, and in the hosted PDF.js demo. The demo isn't getting that for free from the engine. It CSS-scales the existing canvas during the gesture and defers the sharp re-render until about 400 ms after you stop zooming, while the viewer I started in re-rasterizes on every step. Same engine, opposite feel. What I hit was a viewer-configuration gap, not the PDF.js engine failing to keep up.

The strain underneath is still real. Canvas trouble on complex pages is a known PDF.js limit (issue #7265). Teams used to reach for the SVG backend as an escape hatch, but it never really worked and has since been removed. Apryse's 2019 benchmark, from a vendor selling a competing engine, found CAD exports from GrabCAD failing to open or crashing the browser as often as 1 in 10. That's a limit on what's practical in a browser without careful viewer engineering, whichever engine you pick.

And this is where the evidence gets thinnest. Dropbox's famous result, halving 75th-percentile Time to Interactive, was server-side PDFium-to-PNG in 2017, not in-browser WASM. The 2014 microbenchmarks disabled the text layer. So I won't tell you PDFium is faster. On heavy PDFs the lag comes from how the viewer is built, not the engine underneath.

Test what matters to you instead:

Gather your heaviest files: CAD and architectural exports, large scans, layer-heavy documents.
Open each one in every viewer you're considering, and zoom in and out repeatedly on the densest areas.
Time how long it takes to get from the gesture to a sharp render, and watch memory on long scrolls.
Check it on real target hardware, not just your dev machine.

Forms and form fidelity

The assumption going in is usually "PDFium does forms better." It's mostly a wash, with one persistent myth worth clearing up.

AcroForms work on both. PDF.js added AcroForm rendering in Firefox 84 and form JavaScript in 88. PDFium renders and fills them with Chrome and Acrobat fidelity, plus signatures. For the forms you'll actually run into, there's no real gap.

XFA is the part people get wrong. The naive line, "PDFium can't do XFA," is false. PDF.js renders XFA out of the box at the viewer layer (Firefox 93). On the PDFium side it's a build-flag and implementation choice. Chrome's shipped PDFium disables XFA, but the engine has the module and EmbedPDF's own WASM compiles it in. I checked: FPDF_LoadXFA and the XFA packet functions are exported in EmbedPDF's pdfium.wasm. Its plugin just doesn't surface XFA in the UI. So PDF.js gives you XFA rendering for free, and on PDFium the engine has it but you'd wire it up yourself. Not "PDFium can't."

One note on React PDF Kit. The library ships AcroForm only and skips XFA, even though PDF.js the engine could render it. Don't read "PDF.js renders XFA" as "React PDF Kit renders XFA."

But XFA barely comes up anymore. It's deprecated, removed from the PDF 2.0 spec and excluded from PDF/A, surviving only in legacy government, banking, and legal forms. If you don't have XFA, none of this matters. If you do, PDF.js is the lower-effort path. Neither engine is a form-authoring SDK. That's Nutrient, Apryse, or Syncfusion.

Where PDF.js pulls ahead: bundle size, text, and accessibility

The last few sections leaned PDFium's way or came out even. This one doesn't. PDF.js leads on the pieces a viewer is actually made of.

Bundle size and load model

PDF.js is the lighter default, and more of its weight is deferrable. You ship the display layer plus a worker. Reported sizes put the minified display layer around 299 KB (issue #9087), and a source-map breakdown puts it near 840 KB display plus 699 KB worker uncompressed, so roughly 1 to 1.5 MB before gzip, and less over the wire. The CJK cmaps and standard fonts load on demand through cMapUrl and standardFontDataUrl. You don't pay for them unless a document needs them.

PDFium is a fixed cost. It's one WASM binary, fetched and instantiated up front, the same size no matter how simple the document. I measured EmbedPDF's pdfium.wasm at 4.63 MB uncompressed, around 2.1 MB gzipped over the wire, fetched from a CDN by default, plus a one-time instantiation cost on cold start. There's no on-demand splitting of the engine itself. It caches after first load and stays constant, which is the upside, but the up-front number is real. If first paint matters in your app, PDF.js starts lighter.

Text, search, and accessibility

This is the quiet, decisive one. PDF.js builds a transparent text layer of positioned spans over the canvas. That gives you real selectable text, in-document search that maps to actual glyphs, and tagged-PDF accessibility for screen readers, which landed in Firefox 89. Those are the features you build a viewer around.

PDFium hands you none of that in the browser. Dropbox noted that text extraction and positioning were trickier with PDFium than with PDF.js. pdfium-bugs #1523 is a screen-reader user flagging missing selection support. EmbedPDF rebuilds its own text and selection layer on top of PDFium to fill the hole, which works, but it's work the viewer has to redo that PDF.js gives you for free. If you want to understand how this layer actually works, we covered PDF.js layers in a separate article on the React PDF Kit blog.

A smaller security surface

PDF.js runs as ordinary JavaScript using only normal web APIs, so its attack surface is small and browser-standard. PDFium is C++, with the usual memory-safety bug class and historically a larger surface, mitigated by Google's continuous updates, sandboxing, and the browser's WASM sandbox. Both engines restrict the Acrobat JavaScript APIs, and both run client-side now, so files don't have to leave the device.

What this means in a React project

Engine choice eventually becomes a setup choice. This is what each one actually looks like in React and Next.js.

On the PDF.js side, you need pdfjs-dist and a configured worker. React PDF Kit handles the worker for you. It sets GlobalWorkerOptions.workerSrc to a bundled worker file behind a window guard, and lets you override it:

import * as pdfjs from 'pdfjs-dist'

if (typeof window !== 'undefined') {
  const defaultWorkerUrl = new URL(
    'pdfjs-dist/build/pdf.worker.min.mjs',
    import.meta.url
  ).href
  pdfjs.GlobalWorkerOptions.workerSrc = workerUrl || defaultWorkerUrl
}

The viewer's entry components are marked 'use client', so in Next.js App Router you load it as a client component. When something breaks, you debug it with normal JavaScript stack traces in devtools. That's underrated.

On the PDFium side, EmbedPDF boots the engine through a hook. usePdfiumEngine() fetches and initializes the PDFium WASM (from a CDN by default, with a worker: true option), and you hand the engine to a provider:

import { EmbedPDF } from '@embedpdf/core/react'
import { usePdfiumEngine } from '@embedpdf/engines/react'

function App() {
  const { engine, isLoading, error } = usePdfiumEngine()
  // register plugins: viewport, scroll, render, tiling, search, selection
  return (
    <EmbedPDF engine={engine} plugins={plugins}>
      {/* Viewport with render, search, and selection layers */}
    </EmbedPDF>
  )
}

The manual C-style memory model PDFium is known for (malloc/free, FPDF_LoadMemDocument, FPDF_GetLastError) is real, but it lives inside the library. App developers use usePdfiumEngine, not raw memory.

One misconception to clear up: both of these are client-only in Next.js, but the mechanism differs. React PDF Kit uses 'use client'. EmbedPDF uses typeof window guards plus dynamic imports. SSR-skipping isn't a PDF.js-only tax. The real difference is a worker file to resolve versus a WASM binary to fetch, which is a different problem, not a harder one in absolute terms.

If you're on PDF.js and don't want to reimplement worker config and the client-only wrapper for the hundredth time, that's the gap React PDF Kit fills. It's tailored for React, and it's built to save you the weeks that the worker setup and the surrounding viewer features usually cost.

PDFium vs PDF.js: how to choose

Pick PDFium when:

You need Chrome and Acrobat color parity with nothing to configure. PDF.js can match it, but only once you wire up its ICC options, so if you don't control the viewer's config, PDFium gets you there by default.
Your documents are CJK-heavy, or lean toward construction, large-format, or technical drawings where Acrobat parity is the explicit bar.
You're shipping a document-review tool where a wrong color or a dropped glyph is a real problem. PDFium earns its WASM payload here.

Pick PDF.js when:

You want the broader ecosystem and JavaScript-native debugging, the path nearly every React PDF library already takes.
The mature text, search, and accessibility layer matters more to you than fidelity on the cases above.
Color-critical work doesn't force you off PDF.js by itself. The ICC path ships in 5.x, so you can turn on color-managed CMYK when you need it, as long as you clear the config trap above.

Two honest footnotes:

v6 isn't a free upgrade. PDF.js 6 raises the minimum supported browser versions even in its legacy build, so staying on the 5.x line is a real fidelity-versus-browser-support tradeoff.
The comparison dates fast in both directions. Even Dropbox, whose 2017 migration anchors a lot of the received wisdom here, has since moved its previews off PDFium to a commercial SDK.

One honest caveat before you commit: Forms are a nuance, not a clean win for either engine, and even color, the one edge this piece let PDFium keep, turns out to be a PDF.js setting that ships off by default rather than a missing capability. The "PDFium just renders better and faster" reputation rests on dated and vendor evidence with no current neutral benchmark behind it. So don't take my word for it or theirs: prototype both engines on your trickiest documents and see what actually differs.

If you're staying on PDF.js and want the viewer layer handled instead of rebuilt, React PDF Kit's docs and live demos are at react-pdf-kit.dev.

And put a date on whatever you decide. PDF.js ships roughly once a month and PDFium tracks Chromium, so there's no permanent answer here, only the right one for your documents on today's builds.

How to Add PDF Annotations in Vue.js: PDF.js, vue-pdf-embed, @tato30/vue-pdf, and Vue PDF Viewer (2026)

Kittisak Ma — Tue, 04 Aug 2026 00:00:00 +0000

Vue PDF Viewer didn't start as an annotation tool. It started as a viewer. Render a PDF, give it a toolbar, let people zoom and search and print. That's what people asked for first, and for its first year that was the whole product.

Then, our users wanted to mark up the documents they were reading. So we added the first annotation tools in September 2025: highlight, free text, and image. The requests didn't stop there, because a highlighter alone can't say everything people need to say on a document. A highlight means "pay attention here," an underline marks a reference, a strikethrough means "cut this." Force all three through one yellow highlight and you lose the distinction, so underline and strikethrough followed in February 2026. I worked on that plugin. That's the disclosure, and it's also why I can tell you where each option's seams are, ours included.

Here's the part worth knowing before you write any code. Vue PDF Viewer renders with PDF.js, like most of the Vue ecosystem, so PDF.js's own annotation editor was the obvious place to start on the creation side. It creates free text, ink, and stamps, and it has a highlight tool. It has no underline tool and no strikethrough tool. That gap has held for years. And the highlight it does give you is free-form rather than snapping cleanly to a text selection. So the text-selection toolkit ended up being something we built ourselves.

"Annotations" sounds like one feature. It's really three separate jobs. This walks through how to add PDF annotations in Vue.js across four approaches (PDF.js directly, vue-pdf-embed, @tato30/vue-pdf, and Vue PDF Viewer), plus a couple of escape hatches for when none of them fit.

Versions tested: Vue 3.5.x, pdfjs-dist 5.4.530, vue-pdf-embed 2.1.4, @tato30/vue-pdf 2.1.0, @vue-pdf-viewer/viewer 4.3.0 with @vue-pdf-viewer/annotation 1.6.0, on Chrome and macOS.

Rendering, creating, and persisting are three different jobs

There are three problems hiding inside the word "annotation," and conflating them is the most expensive mistake you can make. Someone drops a marked-up PDF into each demo, sees every highlight render perfectly, picks the smallest library, and finds out two sprints later that it can't create a highlight at all.

The first is rendering: a PDF may already contain annotations (highlights, notes, stamps someone added in Acrobat), and your viewer has to display them. This is the easy problem. Every library here handles it, because PDF.js handles it.

The second is creating: your user selects a sentence and highlights it, draws on the page, leaves a comment. Different problem. It needs editing tools, a toolbar, state, and a way to turn a drag of the mouse into an annotation the PDF format understands. This is where the libraries split apart, and where most of them stop.

The third is persisting: the highlight your user just made has to survive a reload, a round-trip to your backend, and ideally open correctly in someone else's PDF reader. Teams tend to find this one last, usually after shipping, when it's too late to change the first two choices.

A library can render annotations perfectly and still create none of its own, or let users create them and then save them where no other reader can read them. Decide which of the three you need before you evaluate anything:

Approach	Render existing	Create new	Persist & export
PDF.js (direct)	Yes	Partial, no underline/strikethrough	DIY, and fragile
vue-pdf-embed	Yes	No	—
@tato30/vue-pdf	Yes	Yes (beta, single-page)	DIY
Vue PDF Viewer	Yes	Yes (5 types)	Save / print / download, XFDF in and out

We'll take them one problem at a time, starting with the easy one.

Rendering existing PDF annotations costs you one prop

Someone marks up a contract in Acrobat. Three highlights, a strikethrough through a clause they want gone, an ink scribble in the margin, one sticky note. They email you the file and your Vue app has to show all of it.

That's one prop.

PDF.js ships an annotation layer that walks the annotation objects already stored in the file and draws them over the rendered page. Both lightweight Vue libraries expose it the same way, as a boolean.

vue-pdf-embed (hrynko's package on npm, not vue-pdf by FranckFreiburger, which is Vue 2 only and abandoned since 2021):

<script setup>
import VuePdfEmbed from 'vue-pdf-embed'
import 'vue-pdf-embed/dist/styles/annotationLayer.css'
</script>

<template>
  <VuePdfEmbed source="/marked-up.pdf" annotation-layer />
</template>

@tato30/vue-pdf does the same job with a per-page API:

<script setup>
import { VuePDF, usePDF } from '@tato30/vue-pdf'
import '@tato30/vue-pdf/style.css'

const { pdf } = usePDF('/marked-up.pdf')
</script>

<template>
  <VuePDF :pdf="pdf" annotation-layer />
</template>

If you forget the stylesheet, the layer mounts invisibly, which is the one catch here and costs an afternoon the first time. Otherwise you get the whole subtype set: link, text, highlight, underline, strikeout, squiggly, ink, stamp, free text. Underline and strikeout included, which matters shortly.

Our own changelog puts a date on just how far rendering ran ahead of creating. Vue PDF Viewer v1.5.0 shipped on 29 October 2024 and rendered highlight, strikeout, underline, squiggly, ink and free text. The first annotation a user of ours could create shipped in September 2025, eleven months later, and it was highlight, free text and image only. Underline and strikethrough creation didn't release until February 2026, sixteen months after we could already draw them on a page.

Creating PDF annotations is where the libraries come apart

Four ways to let a user make a mark, ordered by how much ships versus how much you build.

The PDF.js annotation editor

Everything below except pdf-lib is standing on this, so start here. PDF.js has an editor layer, the same one behind the markup tools in Firefox's built-in viewer. You turn it on and set a mode:

import { AnnotationEditorType } from 'pdfjs-dist'

// on a PDFViewer instance you've already set up yourself
pdfViewer.annotationEditorMode = { mode: AnnotationEditorType.HIGHLIGHT }

// FREETEXT | HIGHLIGHT | INK | STAMP, plus a signature editor in recent builds.
// There is no AnnotationEditorType.UNDERLINE.
// There is no AnnotationEditorType.STRIKEOUT.

That enum is the entire story. Free text, highlight, ink, stamp, and a signature editor built on top of stamp in recent builds. No underline tool. No strikethrough tool. Not on any version, including Mozilla's unreleased development code. This isn't a "not yet," it's the shape the project has had for years, and the annotations it refuses to author are the same ones it renders without complaint if they're already in the file.

On versions: if you're building straight on PDF.js, 6.1.200 is the current release, and none of the above changes. We test against the 5.x line ourselves, because Vue PDF Viewer's peer range (^5.4.530) excludes 6.x by construction.

The highlight tool you do get is free-form. There's a text-selection mode in there, and on a clean single-column page it behaves. Give it a two-column layout with a table in the middle, though, and the snapping gets too unreliable to put in front of users. That's our experience building on it rather than a documented limitation, so weigh it as such. What you can promise is "highlight a region," not "highlight that sentence."

Two more things fall on you. The marks the editor makes are HTML overlays on top of the page, not part of the PDF itself. Draw a highlight in Mozilla's demo viewer, open DevTools, and here is what you actually made:

<div class="annotationEditorLayer highlightEditing">
  <div id="pdfjs_internal_editor_0" class="highlightEditor selectedEditor"
       role="mark" aria-label="Highlight editor"
       style="left: 51.69%; top: 49.9%; width: 39.36%; height: 3.99%;">
    <div class="internal" style="clip-path: url(#clip_path_0);"></div>
    <div class="editToolbar" role="toolbar">…</div>
  </div>
</div>

A percentage-positioned <div> with a clip-path, sitting in a sibling layer above canvasWrapper and textLayer. Note the id: pdfjs_internal_editor_0. Internal, as the name says. It's a DOM node in your app, not a byte in the PDF. Saving it into the file where another reader can see it is a separate job (that's Section 4's problem). And the toolbar is yours to build. All of it: the tool picker, the colour swatches, the delete button, and the state that tracks which tool is active.

@tato30/vue-pdf's editor-layer is that same editor in Vue clothing

This is not a second, separate approach. It's the PDF.js editor from above, wrapped in a Vue component so you're setting a prop instead of managing a viewer instance. That wrapping earns @tato30 a distinction worth naming: it's the only lightweight Vue PDF library that creates annotations at all.

<template>
  <VuePDF :pdf="pdf" :page="page" editor-layer />
</template>

You get the primitives in Vue components: free text, highlight, ink, stamp, plus comments. If drawing is what you need, ink is the primitive here, and it works.

Two limits worth knowing before you commit. It's beta-stage, and interactions are limited to single pages, which matters the moment your review UI scrolls. A contract clause that starts at the bottom of page 4 and finishes at the top of page 5 becomes two separate annotations on two <VuePDF> instances, and stitching them back into one highlight is your code. TaTo30's release notes are unusually straight about the ceiling: other annotation types won't be supported as long as pdf.js doesn't support them. That's the honest answer, and it's also exactly the problem. The library inherits PDF.js's gaps along with its primitives, so underline and strikethrough aren't here either.

You still build the UX. What you save is the wiring, not the toolbar.

pdf-lib, for when you just need it burned in

Different shape entirely. pdf-lib has no viewer and no UI. It's a framework-agnostic library that opens a PDF, draws into it, and hands you back bytes. Useful server-side, or as a pre-render step before the document ever reaches your Vue component.

import { PDFDocument, rgb } from 'pdf-lib'

const pdfDoc = await PDFDocument.load(existingBytes)
const page = pdfDoc.getPages()[0]

page.drawText('APPROVED', { x: 50, y: 700, size: 24, color: rgb(0.8, 0, 0) })

const stamped = await pdfDoc.save()

The catch is what those marks are. They're content drawn into the page, not standard PDF annotation objects, so they won't appear in Acrobat's or Preview's annotation panel and nobody can select, edit or delete them afterward. That's the point if you're stamping an approval watermark. It's the wrong tool if a human needs to take the mark back off.

Maintenance, honestly: v1.17.1 is the latest, released November 2021. Nothing since. It still works, and plenty of production pipelines run on it, but you're adopting a frozen dependency.

The Vue PDF Viewer annotation plugin

Our option, and the disclosure from the top of this article applies. Activation is one prop:

<script setup>
import { VPdfViewer } from '@vue-pdf-viewer/viewer'
import VPdfAnnotationPlugin from '@vue-pdf-viewer/annotation'
</script>

<template>
  <VPdfViewer src="/marked-up.pdf" :plugins="[VPdfAnnotationPlugin()]" />
</template>

That gets you a create UI for highlight, underline, strikethrough, free text and image (the docs call the image one Image Overlay). Underline and strikethrough are in there because we wrote the text-selection toolkit ourselves rather than inheriting PDF.js's editor, which is the whole reason this article exists. Highlight, free text and image came first in September 2025; underline and strikethrough followed by request in February 2026.

Now the edges, because you'll find them anyway. Comments are view-only today: the panel displays comment threads already in the file, and there's no create button. Drawing, shapes and a stamp palette aren't in the plugin today (the image tool covers arbitrary user-supplied images, not preset approval stamps), and e-signatures and form-field authoring aren't either; I won't even tell you those two are planned, because they aren't. If ink drawing is your core requirement today, the honest answer is @tato30's editor-layer or raw PDF.js, not this plugin.

Persisting PDF annotations is the part that bites you later

Your user highlights a clause and closes the tab. Now what? That question decides more than rendering and creating combined. There are three sub-questions inside it. Where does the annotation data live, how is it serialized (as XFDF, the XML standard other readers can import, or as JSON only your own app understands), and can anything besides your app read it back?

PDF.js editor. You save the annotations yourself and store them somewhere. Then there's the problem Section 3 handed forward: those editor overlays are DOM nodes, and getting them into the file is a job PDF.js won't do for you. Your highlights work in your app. Open the same file in Preview and they were never there.

@tato30/vue-pdf. Same editor, same problem, plus the single-page caveat shaping how you batch what you save.

pdf-lib. The marks are drawn straight into the page, which is the point: there's no separate save step, they're just part of the file pdf-lib hands back. No round-trip either. They're page content now, not annotations, so there's nothing to export, edit or remove.

Vue PDF Viewer. Save, print and download with annotations baked in, plus XFDF export and import through the XFDF Controller in the Instance API. That shipped on 3 July 2026 in annotation v1.6.0 and viewer v4.3.0.

// `viewer` is a template ref on the <VPdfViewer> component
// export the current annotations as an XFDF string, store it wherever you like
const xfdf = await viewer.value.annotationXfdfControl.exportToXfdf()

// later, on a fresh mount of the same document (importFromXfdf is synchronous)
const { annotations, skipped, errors } = viewer.value.annotationXfdfControl.importFromXfdf(xfdf)

What comes back is a document, not a private blob. A single highlight serializes to something like this:

<?xml version="1.0" encoding="UTF-8"?>
<xfdf xmlns="http://ns.adobe.com/xfdf/" xml:space="preserve">
  <f href="contract.pdf"/>
  <annots>
    <highlight page="0" rect="72.0000,690.2000,331.5000,704.8000"
               color="#FFE066" opacity="0.4"
               name="6f1c…" title="Vue PDF Viewer"
               date="D:20260703T101500" creationdate="D:20260703T101500"
               flags="print"
               coords="72.0000,704.8000,331.5000,704.8000,72.0000,690.2000,331.5000,690.2000"/>
  </annots>
</xfdf>

A zero-based page index, the colour, and the quad points of the highlighted text, in a schema Acrobat and Preview already parse. The <f href> names the document the marks belong to; coords is an attribute, not a child element, because that's the one spelling Acrobat actually reads. That's why the string is worth storing in your own database: it's readable by things that aren't your app.

One precision, because I'd rather you hear it here than in a support ticket: this is programmatic, not a button. There's no end-user Export XFDF item in the toolbar. You call it from the Instance API and you decide when. If what you want is a file on the user's disk rather than a string, exportToXfdf({ download: true }) does that.

And it's not only the marks your users made. Export walks the whole document and merges what's in the editor with the annotations already in the file when it loaded, so a PDF that arrives with ink from someone's tablet and squares from a reviewer's Acrobat round-trips those too. Thirteen annotation types survive the trip, not just the five the toolbar can create.

The reason XFDF matters isn't that it's ours. It's that a standards-based round-trip is the exact thing PDF.js's overlays can't do and the exact thing pdf-lib gives up by drawing straight into the page. A highlight your reviewer makes in your Vue app opens in their lawyer's Acrobat. That's the whole argument, and it's a format argument rather than a product one.

Signatures deserve a mention, since for many people they're the whole reason for using annotations. Free-text and image annotations can serve as lightweight signatures, and persistence is what makes one stick: an image that vanishes on reload isn't a signature. But none of these lightweight Vue options is a real e-signature workflow product.

When you actually need the enterprise tier

Two options sit above everything discussed so far, and it would be dishonest to leave them out.

Syncfusion's EJ2 Vue PDF Viewer ships text markup, shapes, stamps, ink, free text, sticky notes, measurement tools, form filling, e-signatures and redaction. Nutrient (formerly PSPDFKit) covers 17+ annotation types with create, edit and remove available through the UI or programmatically, XFDF and JSON round-trips, and real-time collaboration sync.

Both are commercial, both are priced accordingly, and both are genuinely more capable than anything else on this page. Reach for them when annotation breadth, compliance or multi-user collaboration is the product. Not when markup is a supporting feature rather than the core of the product or system.

Picking a path

Match the tool to what you're actually building, not to the shortest README.

Displaying markup that already exists. vue-pdf-embed, or @tato30/vue-pdf if you want per-page control. One prop, MIT, done this afternoon. Reaching past this tier for a read-only viewer is how projects acquire dependencies they regret.

Lightweight DIY markup, and you're willing to build the UI. The PDF.js editor layer directly, or @tato30's editor-layer for the Vue wrapping. You get free text, highlight, ink and stamp. You write the toolbar, the state, and the persistence. Budget real time for the last one.

Server-side or pre-render stamping, no UI at all. pdf-lib. Frozen since 2021 and fine for the job, as long as the job is burning marks in permanently.

Shipping a review or markup feature without building the toolbar. Vue PDF Viewer, and here the disclosure at the top applies: it's the only option that ships underline and strikethrough creation, because PDF.js has no tool to create them and everything downstream inherits that gap. Add the XFDF round-trip and the toolbar you'd otherwise be writing, and the trade is a commercial licence against the weeks in Section 3. If your project can't take a paid licence, that trade doesn't exist and @tato30's editor-layer is your answer.

Compliance, collaboration, or 17+ annotation types. Syncfusion or Nutrient.

Here's the full picture, pdf-lib included:

	PDF.js (direct)	vue-pdf-embed	@tato30/vue-pdf	pdf-lib	Vue PDF Viewer
License	Apache 2.0	MIT	MIT	MIT	Commercial (perpetual)
Latest version	6.1.200 (5.4.530 used here)	2.1.5 (Jun 2026)	2.1.0 (May 2026)	1.17.1 (Nov 2021)	viewer 4.3.0 + annotation 1.6.0 (3 Jul 2026)
Render existing	Yes	Yes (`annotation-layer`)	Yes (`annotation-layer`)	No (not a viewer)	Yes
Create (types)	Free text, highlight, ink, stamp	None	Free text, highlight, ink, stamp, comments	Text, image, shapes (as page content)	Highlight, underline, strikethrough, free text, image
Create UI shipped	No, primitives only	n/a	Partial, beta	No UI at all	Yes
Persist / export	DIY, overlays may not reach the PDF binary	n/a	DIY, same overlay caveat	Burned in, no round-trip	Save / print / download + XFDF import/export (programmatic)
Known limits	No underline or strikethrough tool, free-form highlight	Render only	Beta, single-page interactions	Not standard annotation objects, unmaintained	Comments view-only, no stamps or e-signatures
Vue 3	Manual setup	Yes	Yes	Framework-agnostic	Yes (purpose-built)

Versions verified 16 July 2026. Releases move. Re-check before you commit to any of this.

What to decide before you install anything

Rendering is one prop. Creating is where the libraries come apart, and the gap runs deeper than any of them advertise: PDF.js has no underline or strikethrough tool, so nothing built on PDF.js has one either unless someone sat down and wrote it. Persisting is the one that surfaces after launch, when someone opens your reviewed contract in Acrobat and finds a clean page.

So the useful question isn't which library is best. When you ask how to add PDF annotations in Vue, you're asking about three jobs, and the one that matters is whichever you're actually signing up for. Answer that first and most of this page collapses into one row of the table.

If it turns out you need the create UI and the round-trip, the annotation plugin docs and live demo are the fastest way to check whether it fits, including the parts it doesn't do.

How to Build a React PDF Viewer for Next.js in Minutes

Kittisak Ma — Wed, 11 Jun 2025 12:01:00 +0000

Since my last post on Best 4 Methods to Build a PDF Viewer in React.js: PDF.js, react-pdf, and More, my team and I launched React PDF in March 2025, a library that help React developers easily add a React PDF viewer to their Next.js apps.

In this article, I'll show you how to display the default PDF Viewer in Next.js in just a few steps. I'll also share a few use cases to help you make the most out of React PDF in your own projects.

Why React PDF?

If you’re building a PDF viewer in a Next.js app, you need a component that just works. React PDF stands out for its balance of powerful features and simple setup. You can drop it into your Next.js project with little work and handles most of what React devs expect. Its API feels natural if you know React, so no relearning is required.

React PDF offers everything most apps need right out of the box. Here’s what you get:

React-First: Designed specifically for React.js developers, React PDF uses familiar component-based patterns, and hooks fit right in with your Next.js app’s structure.
Customizable: You can style or customize easily. From changing icons and colors to match your branding or customize your toolbar layout with React Context APIs to fit your app's needs.
Responsive Design: Fits devices big or small, so mobile users can scroll, zoom, and interact with ease.
High Performance: Optimized for handling large PDFs without sacrificing speed or performance.
No surprises: The documentation is clear, and support is strong. Bugs get addressed fast. Most developers will find everything they need quickly.

Step 1: Set up a Next.js Project

In this tutorial, I'll use StackBlitz to demonstrate how to build a React PDF Viewer in a Next.js project. Here's how to get started.

1.1 Visit StackBlitz & Create a New Project

Go to https://stackblitz.com. Assuming you already have an account and are logged in, click “New Project” in the top-right corner. You’ll see a list of available frameworks—select Next.js.

1.2 Wait for StackBlitz to Set Things Up

StackBlitz will automatically install the necessary dependencies and launch your Next.js project in the browser.

That’s it! You're now ready to integrate React PDF Viewer into your StackBlitz-based Next.js project.

Step 2: Integrate React PDF into a Next.js Project

2.1 Install React PDF

First, install the @pdf-viewer/react package in your project.
In the StackBlitz terminal, press Ctrl + C to stop the current process, then run the following command:

npm install @pdf-viewer/react

Wait for the installation to complete. This should only take a few seconds.

If you're installing this library in your own Next.js project, check out the installation guide for more details.

2.2 Set Up the Viewer

After installing, follow these steps to set up the PDF viewer:

💡 Pro Tip: Always use client-side rendering for these components using dynamic imports to prevent hydration mismatches and SSR-related issues with PDF rendering.

Add RPConfig at the Root Level

The RPConfig component provides the global configuration for React PDF and should wrap your entire app.

Place the RPConfig component at the root of your application (e.g., in _app.tsx or a root layout component). Make sure it only runs on the client side.

components/AppProviders.tsx

'use client';
import { RPConfig, RPConfigProps } from '@pdf-viewer/react';
import { type PropsWithChildren } from 'react';

function AppProviders({
  children,
  ...props
}: PropsWithChildren<RPConfigProps>) {
  return <RPConfig {...props}>{children}</RPConfig>;
}
export default AppProviders;

components/LazyAppProviders.tsx

'use client';
import dynamic from 'next/dynamic';

const LazyAppProviders = dynamic(() => import('./AppProviders'), {
  ssr: false,
});
export default LazyAppProviders;

app/layout.tsx

import { type PropsWithChildren } from 'react'
import LazyAppProviders from './components/LazyAppProviders'

export default function RootLayout({ children }: PropsWithChildren) {
 return (
   <html lang="en">
     <body>
      <LazyAppProviders licenseKey="your-license-key">
        <main>
          { children }
        </main>
      </LazyAppProviders>
    </body>
   </html>
 )
}

Step 3: Create a Reusable PDF Viewer Component

To keep your code clean and reusable, it’s a good practice to wrap the viewer in its own component. This also makes it easier to customize or extend the viewer later as your app grows.

Build the `AppPdfViewer` component

components/AppPdfViewer.tsx

'use client'
import { RPProvider, RPDefaultLayout, RPPages } from '@pdf-viewer/react'

interface OwnProps {
 src: string
}

const AppPdfViewer = (props: OwnProps) => {
 const { src } = props
   return (
     <RPProvider src={ src }>
       <RPDefaultLayout>
         <RPPages />
       </RPDefaultLayout>
     </RPProvider>
   )
}

export default AppPdfViewer

Create a Lazy-Loaded Wrapper Component

Since React PDF is client-side only, we’ll also create a lazy wrapper to prevent SSR issues and hydration errors in Next.js.

components/LazyAppPdfViewer.tsx

'use client'
import dynamic from 'next/dynamic'

const LazyAppPdfViewer = dynamic(() => import('./AppPdfViewer'), {
 ssr: false
})
export default LazyAppPdfViewer

Use the PDF Viewer in Your App

You can now use LazyAppPdfViewer anywhere in your Next.js application.

Here's an example of how to use it on the index page:

app/index.tsx

import LazyAppPdfViewer from '../components/LazyAppPdfViewer';

export default function Home() {
  const pdfUrl = "https://cdn.codewithmosh.com/image/upload/v1721763853/guides/web-roadmap.pdf"
  return (
   ...
   <div className="pdf-viewer mb-3 w-[500px] lg:w-[992px]">
    <LazyAppPdfViewer src={ pdfUrl } />
   </div>
   ...
  )
}

That’s it! You should now see your PDF in action.

Note: At the moment, Hot Module Reload (HMR) does not apply css style automatically to a component that dynamically import with ssr: false. It is recommended to refresh the page after changing the component.

Looking for a Faster Setup?

If you want to skip boilerplate and get straight to building, check out the React PDF Starter Toolkit.

It includes ready-to-use templates for:

React (Vite / Webpack)
Next.js (JavaScript / TypeScript)

Each template comes with a clean folder structure and sample code so you can build a PDF viewer quickly without spending hours configuring dependencies. Just clone, customize, and go. 🚀

Common Use Cases

Customize the PDF Viewer to Match Your Branding

Every project has its own look and feel. @pdf-viewer/react makes it easy to tailor the PDF viewer’s appearance so it fits right into your app — whether it’s light mode, dark mode, or a custom color palette.

With the customVariables prop in the RPTheme component, you can quickly apply brand colors to the viewer without digging into complex CSS overrides.

Here’s a simple example of applying a custom background color:

...
const AppPdfViewer = (props: OwnProps) => {
 const { src } = props
   return (
     <RPProvider src={ src }>
       <RPTheme
          customVariables={{ '--rp-toolbar-background': '#F7E3D5' }}
          customDarkVariables={{ '--rp-toolbar-background': '#874707' }}
        >
         <RPDefaultLayout>
           <RPPages />
         </RPDefaultLayout>
       </RPTheme>
     </RPProvider>
   )
}

export default AppPdfViewer

Light Mode

Dark Mode

Why this is useful:

Provides a consistent branded experience
Works out of the box with theme switching (light/dark mode)
Saves time styling PDF viewers for modern UIs

Curious about more CSS variables you can override? Check out Overriding Style for details.

Customize Any Toolbar Icon

The @pdf-viewer/react component offers flexibility in customizing the user interface. You can easily replace any default icons with your own, allowing you to maintain brand consistency or match with the rest of your application’s UI.

Here’s an example of how to replace the default toolbar icons in @pdf-viewer/react with Lucide Icons, allowing for a more customized and consistent user interface.

To get started, install the Lucide Icons package:

npm install lucide-react

Once installed, you can import and use Lucide icons to replace the default icons in @pdf-viewer/react.

...
const AppPdfViewer = (props: OwnProps) => {
  const { src } = props;
  const defaultIconDimension = { width: 20, height: 20 };
  return (
   ...
    <RPDefaultLayout
      icons={{
        zoomInIcon: <ZoomInIcon {...defaultIconDimension} />,
        zoomOutIcon: <ZoomOutIcon {...defaultIconDimension} />,
        downloadIcon: <DownloadIcon {...defaultIconDimension} />,
        searchIcon: <SearchIcon {...defaultIconDimension} />,
        ...
      }}
    >
      <RPPages />
    </RPDefaultLayout>
   ...
  )
}
...

At this point, all of the viewer's toolbar icons have been successfully replaced.

If you'd like to see the example code in action, check out my StackBlitz for this article.

Conclusion

Adding a PDF viewer to your Next.js app is simple with React PDF viewer. The setup takes just a few steps, and you instantly get a flexible, fast and robust tool. The viewer works responsively across different devices and screen sizes. You can easily style it to match your app’s look or let users zoom in and jump to pages without any hassle.

React PDF is a great choice for:

Simple PDF reading experiences
Document workflows and approval systems
AI-powered tools that need to display PDFs
Business and productivity apps with embedded documents

It takes care of PDF rendering behind the scenes — so you can focus on building great features your users want.

Try it out and see how easy it is to upgrade your project’s PDF viewing experience! 🚀

👉 Want to explore more? Check out the full React PDF documentation to see what else you can build.

If you found this helpful, let me know! And if you build something cool with React PDF, I’d love to hear about it.

🔥 Understanding PDF.js Layers and How to Use them in React.js

Kittisak Ma — Mon, 26 May 2025 11:58:00 +0000

PDF files are everywhere but working with PDFs in a React.js project can be frustrating. You might run into clunky plugins, awkward iframes, or glitches that break the user experience. PDF.js gives you a powerful, open-source JavaScript library to display and interact with PDF files right in the browser.

Now, figuring out how to use PDF.js in your React project can be daunting at first. To leverage PDF.js's capabilities, it's important to understand how its layered structure works.

If you’ve ever wondered, “How do I highlight text selection?” or “How do I interact with links inside the PDF?” or even “How do I build advanced features like annotations?”, the answer usually lies in understanding these layers.

In this guide, you'll see how PDF.js splits content into layers, what those layers do, and how you can use them in your next React project. Let’s get going!

React PDF: Flexible and Powerful React PDF Viewer

Before diving into the technical side of things, let me introduce you to React PDF—a library I’ve been working on: React PDF is a handy PDF Viewer that renders PDFs right within your React.js or Next.js app. It packs over 20 features, including out-of-the-box default toolbar, customization and responsive design, so your users never have to leave your site to interact with your documents.

React PDF can integrated into various applications whether it's for a Document Management System, Workflow Management System, AI tool or simply as a PDF reader.

If that sounds interesting, I’d love for you to give React PDF a try. Your support helps me keep creating awesome tools and tutorials like this one. ❤️

Overview of PDF.js Layers

Before we dive in, Here’s a quick overview of the four main layers in PDF.js. Each layer handles a specific aspect of rendering or user interaction:

Canvas Layer: This layer draws the core visuals of your PDF—shapes, images, and text as graphics. It forms the base of your PDF Viewer.
Text Layer: Placed above the canvas, this layer lets users select and search text.
Annotation Layer: This layer manages interactive items like links, form fields, and highlights, so users can click, enter information, or move around the document.
Structural Layer: This layer keeps everything in order, handling layout, alignment, and scaling for all other layers.

By separating these roles into different layers, PDF.js stays organized and easy to update when you need to adjust or add features.

Let’s start by creating a fresh React project to integrate PDF.js.

Step 1: Set up React.js Project

In this article, I use Codepen as a code editor. If you want to follow along, feel free to follow along the steps below.

Create a new Pen on CodePen.
Click the Settings button (top-right corner of the editor).
In the Pen Settings dialog:
- Go to the JavaScript tab.
- Set the JavaScript Preprocessor to 'Babel'.
- Under 'Add External Scripts / Pens', search for and add: react & react-dom
Click Save & Close.
Now you can write React code using JSX in the JavaScript editor like below.

Step 2: Integrate PDF.js into a React project

First, let’s configure your React project to use the pdfjs-dist library.

Open Pen Settings: Click on the Settings button at the top of your Pen.
Go to JavaScript Tab: In the popup, switch to the JS tab.
Add Packages In the Add Packages box, search for and add pdfjs-dist.
Save and Close: Click the button to apply changes
Update Import Statement CodePen might auto-generate an import that doesn't work correctly. Replace it like so

  // ❌ Wrong (auto-generated)
  // import pdfjsDist from "https://esm.sh/pdfjs-dist";

  // ✅ Correct
  import * as PDFJS from "https://esm.sh/pdfjs-dist";

Add PDF.js Worker and Configure It You'll need to explicitly import and configure the worker. Here's the complete setup

  import React from "https://esm.sh/react";
  import ReactDOM from "https://esm.sh/react-dom/client";
  import * as PDFJS from "https://esm.sh/pdfjs-dist";
  import * as PDFWorker from "https://esm.sh/pdfjs-dist/build/pdf.worker.min";

  try {
    PDFJS.GlobalWorkerOptions.workerSrc = PDFWorker;
  } catch (e) {
    window.pdfjsWorker = PDFWorker;
  }

Explanation
Before loading the PDF, we need to configure the PDF worker. The worker is responsible for processing the PDF in a separate thread, improving performance.

That’s it! You’re now set up to start experimenting with PDF.js layers within a React environment. So let's get to the layers.

1. Canvas Layer

Purpose

The Canvas Layer is the foundation—it’s where PDF.js draws the visual elements such as images, shapes, and text (as graphics). Essentially, what you see on-screen is coming from this layer.

How It Works

PDF.js uses the HTML <canvas> element to display the PDF's visual content
It utilizes the browser's 2D canvas API for high-performance rendering.
This means your PDF content will look consistent and accurate across various screen sizes and devices.

Use Cases

Ideal for non-interactive or static PDF content.
It renders the document as an image, ensuring PDF’s fonts, colors, and layouts are consistent across all devices.

Example of Canvas Layer Code with React

Here’s a quick CodePen demo showcasing a minimal Canvas Layer setup in React.js.

📜 How the Code Works

Below, I’ll walk through the major steps for rendering a PDF page onto the canvas.

(1) Fetching and Loading the PDF

const PDF_SRC = "https://pdfobject.com/pdf/pdf_open_parameters_acro8.pdf"
...
React.useEffect(() => {
  processLoadingTask(PDF_SRC)
}, [])
function processLoadingTask(source) {
    const loadingTask = PDFJS.getDocument(source);
    loadingTask.promise
     .then((docProxy) => { ... })
     .then((page) => {
        ...
        canvasLayer.current.width = width;
        canvasLayer.current.height = height;
        const context = canvasLayer.current.getContext("2d");
        const renderContext = {
            canvasContext: context,
            viewport: viewport
        };
        return page.render(renderContext);
     })
 }

Explanation:

The processLoadingTask method starts the PDF loading process using PDFJS.getDocument(source) from pdfjs-dist.
Once the PDF is loaded from PDF_SRC, we obtain a docProxy—a PDF document instance that contains all pages of the PDF.
In this example, only the first page is used for rendering.
The total number of pages is retrieved from docProxy.numPages and stored in the totalPages state.

(2) Rendering the Canvas Layer

 ...
 const canvasLayer = React.useRef()
 const [pdfDimension, setPdfDimension] = React.useState({
   width: 0,
   height: 0
 });
 ...
 return ( 
     ...
      <div
        class="pdf__canvas-layer"
        style={{
         height: `${pdfDimension.height}px`,
         width: `${pdfDimension.width}px`,
         border: '1px solid #dfdfdf',
         margin: '0 auto'
        }}
      >
       <canvas ref={canvasLayer} />
      </div>
     ... 
 )

Explanation

After the PDF is loaded and we have the first page object then:

Scales the canvas to match the PDF page dimensions by updating pdfDimension.
A <canvas> element (canvasLayer) is used to render the PDF page as an image.
The rendering process is handled by page.render(renderContext), where canvasContext paints the page content onto the canvas.

This ensures the final output accurately matches the original PDF’s appearance.

2. Text Layer

Purpose

The Text Layer ensures that the text in your PDF is selectable, searchable, and accessible. While the Canvas Layer does the heavy lifting of rendering visuals, the Text Layer is what lets you highlight and copy actual text.

How It Works

PDF.js extracts the text content separately from the PDF.
It positions each piece of text exactly over the underlying canvas, using absolutely positioned <div> elements.
Even though you might not see these text <div> visually (they’re often transparent), they’re there to support selection and searching.

Use Cases

Enable text selection and copying from the PDF.
Text layer is crucial for accessibility, as it enables screen readers to interpret the content.
Provide text searching and highlighting within the PDF viewer.
Keep the text aligned with the rendered PDF page

Text layer Code Example

Here’s a React.js CodePen example that demonstrates a Text Layer in action:

With this text layer, you can use your mouse to select text directly on the PDF.

📜 How the Code Works

(1) Fetching and Loading the PDF

Identical to the steps in the Canvas Layer—we load the PDF document first.

(2) Structuring the Layers

return (
  ...
  <div class="pdf-layers" style={{ ... }} >
    <div class="pdf-layer__canvas">
       <canvas ref={canvasLayer} />
    </div>
    <div ref={textLayer} class="pdf-layer__text" />
  </div>
)

Explanation:

The pdf-layers is a container that holds both the Canvas Layer and the Text Layer.
The Canvas Layer (canvasLayer) displays the PDF page visually.
The Text Layer (textLayer) is styled to sit on top of the canvas, enabling text selection.

(3) Rendering the Text Layer

function renderTextLayer(page) {
   const viewport = page.getViewport({ scale: 1 });
   const { scale } = viewport;
   textLayer.current.style.setProperty("--total-scale-factor", `${scale}`);
    page.getTextContent().then((content) => {
      const renderTask = new PDFJS.TextLayer({
        container: textLayer.current,
        textContentSource: content,
        viewport: viewport.clone({ dontFlip: true })
      });
      return renderTask.render();
    });
  }

Explanation:

Render the text layer with renderTextLayer(page) function.
page.getTextContent() retrieves the text data from the PDF page.
This data is passed into a new PDFJS.TextLayer, specifying:
- container: The DOM element where the text will be rendered.
- textContentSource: Extracted text data from the PDF page.
- viewport: Define text positioning and scaling.
renderTask.render() overlays invisible but selectable text <div> over the canvas.
Check the CSS panel in CodePen to understand how the canvas and text layers are stacked together.

3. Annotation Layer

Purpose

The Annotation Layer handles interactive elements like hyperlinks, highlights, form fields, and comments. If you need your PDF viewer to support internal linking (jumping to different pages), or if your PDFs have fillable forms, this layer is for you.

How It Works

PDF.js extracts annotation data (links, form fields, etc.) from the PDF.
It overlays these data as interactive HTML elements (e.g. <a>, <input>, <textarea>), which sit above the Canvas Layer and Text Layer positioned using CSS.
This layer ensures that users can click, type, and interact without altering the PDF’s static visuals.

Use Cases

Clicking on links within PDF to navigate between pages.
Rendering highlights, underlines, and notes from PDF annotations.
Displaying interactive form fields within a PDF.

Annotation layer Code Example

Check out this CodePen example on the Annotation Layer for React.js:

You can click the links inside the Codepen to change the PDF's page.

📜 How the Code Works

(1) Fetching and Loading the PDF

Again, the same initial PDF loading steps as before.

(2) Structuring the Layers

return (
  ...
  <div class="pdf-layers" style={{ ... }} >
    <div class="pdf-layer__canvas">
       <canvas ref={canvasLayer} />
    </div>
    <div ref={textLayer} class="pdf-layer__text" />
    <div ref={annotationLayer} class="pdf-layer__annotation" />
  </div>
)

Explanation:

We add another <div> for the Annotation Layer within pdf-layers.
The Annotation Layer is positioned on top of the Canvas Layer and Text Layer.

(3) Rendering the Annotation Layer

 ....
 const annotationLayer = React.useRef();
 ...
 function getAnnotationsAsync(page) {
    return page.getAnnotations({ intent: "display" });
 }
 function renderAnnotationLayer(page) {
    const viewport = page.getViewport({ scale: 1 });
    annotationLayer.current.replaceChildren();
    getAnnotationsAsync(page).then((annotations) => {
      annotations.current = annotations;
      const pdfAnnotationLayer = new PDFJS.AnnotationLayer({
        div: annotationLayer.current,
        ...
      });
      return pdfAnnotationLayer.render({
        ...
        annotations,
        ...
      });
    });
 }

Explanation:

getAnnotationsAsync() retrieves all annotation data from the PDF page—such as links, form fields, and highlights.
The viewport is cloned using viewport.clone({ dontFlip: true }) to ensure correct positioning and scaling for the annotation layer.
renderAnnotationLayer(page) handles rendering by:
- Clearing or replacing any existing annotation elements inside the annotationLayer.current.
- Creating a new PDFJS.AnnotationLayer instance to manage rendering.
- Calling pdfAnnotationLayer.render({ ... }) with: The annotations retrieved from the page, the cloned viewport, the container where annotations should appear, and so on.

This ensures that annotations are accurately rendered on top of the PDF page.

(4) Handling Internal Link Clicks

...
const annotationEventAbortCtrl = React.useRef();
...
function bindAnnotationLayerEvent(page) {
    if (annotationEventAbortCtrl.current) {
      // Already binded
      return;
    }
    annotationEventAbortCtrl.current = new AbortController();
    const { signal } = annotationEventAbortCtrl.current;
    annotationLayer.current.addEventListener(
      "click",
      async (event) => {
        let annotationTarget = event.target.parentNode;
        if (!annotationTarget) {
          return;
        }
        const id = annotationTarget.dataset.annotationId;
        if (!id) {
          return;
        }
        const annotationLinkId = (await getAnnotationsAsync(page)).find(
          (ele) => ele.id === id
        );
        if (!annotationLinkId) {
          return;
        }
        const pageIndex = await pdfDocProxy.current.getPageIndex(
          annotationLinkId.dest[0]
        );
        setCurrentPage(pageIndex + 1);
      },
      { signal }
    );
  }

Explanation:

This function listens for clicks on internal links (annotations) in the PDF.
When a user clicks a link, it checks if the clicked target has an associated annotationId.
If found, it looks up the annotation to get its destination using getAnnotationsAsync(page).
Then it uses getPageIndex() to find which page the link points to.
Finally, it updates the current page with setCurrentPage() to navigate to the target page.

(5) Handling Page Navigation

A simple navigation bar lets users switch between pages.

...
const [currentPage, setCurrentPage] = React.useState(3);
const [totalPages, setTotalPages] = React.useState(0);
...
React.useEffect(() => {
  processRenderPdfLayers(PDF_SRC);
}, [currentPage]);
...
return (
 <div class="page-navigation">
    <button
       disabled={currentPage <= 1}
       onClick={() => setCurrentPage(currentPage - 1)}
    >
     &larr;
    </button>
    <span>
     {currentPage} / {totalPages}
    </span>
    <button
        disabled={currentPage >= totalPages}
        onClick={() => setCurrentPage(currentPage + 1)}
    >
     &rarr;
    </button>
  </div>
)

Explanation:

The currentPage value updates when navigation buttons are clicked.
The useEffect with currentPage dependency ensures that all layers are re-rendered when the page changes.
This ensures all layers—Canvas, Text, and Annotation—stay in sync.

4. Structural Layer

Purpose

Think of the Structural Layer as the master layout manager. It keeps the Canvas, Text, and Annotation layers correctly aligned, scaled, and positioned when users zoom in or out, or when the window is resized.

This layer is a must-have when creating a PDF viewer as it serves as the foundation that glues all other layers together.

How It Works

The Structural Layer is typically implemented by a container element (<div>) that wraps all other layers.
Maintain consistent positioning among layers so they don’t drift apart during zooms or scrolls.
Act as the foundation that ties everything together, so your PDF viewer remains cohesive.

Use Cases

Ensure a consistent user experience across different screen sizes and resolutions.
Enable smooth zooming by scaling all layers proportionally.
Centralize navigation and layout logic (e.g. controlling how the viewer scrolls from one page to another.)

In our code examples, the <div ref="pdfLayersWrapper" class="pdf__layers"> element serves as the Structural Layer, wrapping for other layers:

<div ref="pdfLayersWrapper" class="pdf__layers">
  <div class="pdf__canvas-layer">
    <canvas ref="canvasLayer" />
  </div>
  <div ref="textLayer" class="pdf__text-layer"></div>
  <div ref="annotationLayer" class="pdf__annotation-layer"></div>
</div>

Why is this important?

The Structural Layer wrapper ensures the Canvas, Text, and Annotation Layers all stay in sync, even when you zoom or flip through pages.
You can customize the wrapper to handle special behaviors like lazy-loading pages, scroll snapping and other performance optimizations.

How Layers Work Together

Here’s how all four layers in PDF.js work together in harmony:

Rendering Process:
Each page is first drawn onto the Canvas Layer (visual content). Next, the Text Layer is layered on top to enable selection and searching. Finally, the Annotation Layer is placed at the very top, providing interactive elements like links and form fields.
Interactivity:
The Annotation Layer handles user events (like clicking on links or typing into form fields), while the Text Layer ensures text can be highlighted, copied, or searched.
PDF Viewer:
The Structural Layer wraps everything up, ensuring that zooming, resizing, and navigation across pages remain consistent. It keeps all layers aligned and responsive, so users get a polished viewing experience.

Beyond the Fundamentals

PDF.js gives you the basics for working with PDFs in JavaScript, but plugging it into a React project means you'll want more control.

Customize UI: Use React hooks and state to create a smooth, custom viewer that fits right into your app.
Handling Large PDFs: For large PDFs, skip loading the whole file up front. Choose lazy loading or virtualization to keep your app feeling quick, even with hundreds of pages.
Adding Toolbar Control: Build your own toolbar with features like zoom, page jumps, and download options, so users get a great experience.

With the right setup, PDF.js and React work together to handle big files and let you shape the viewer to fit your project.

Conclusion

I’ve worked with PDF.js across many React.js projects, from straightforward file previews to detailed, interactive document tools. Its layered structure is always the foundation.

This setup matters because you get full control over each part of the PDF viewer. You can tune specific layers to boost performance or improve the user interface. It’s easy to refine how your viewer responds to things like search, form input, or user actions.

By understanding these layers, you will be able to optimize PDF.js implementations, customize features, and deliver a better user experience. Whether you’re building a simple React PDF Viewer or a complex Document Processing System, leveraging these layers effectively will set your project up for success.

React PDF: The PDF Viewer Built for React.js Developers 🚀

If you enjoyed this article, I’d love for you to check out React PDF. It’s a PDF Viewer built from the ground up for React and Next.js applications. Whether you’re just starting out or already running a large-scale app, React PDF got you covered.

Designed with developers in mind, React PDF offers:

Out-of-the-box features - Check out the Getting Started guide
Customizable look and feel - Learn how to customize components
Web Responsive layouts - See how the React PDF Viewer renders on mobile view
Developer-friendly APIs - Explore the full API documentation for more information

Your support encourages me to keep building tools and publish content for the React community. Thank you for checking out React PDF in advance! 🙏

🚀 Launch a PDF Viewer in Nuxt Using @vue-pdf-viewer [Guide for 2025] 🔥

Kittisak Ma — Tue, 06 May 2025 12:00:00 +0000

PDF viewing is now a must-have for modern web apps, from online contracts to digital classrooms. If you’re building with Nuxt, you want tools that fit right in and work fast. That’s where @vue-pdf-viewer shines 🌟

@vue-pdf-viewer lets you open, zoom, and interact with PDFs right inside your Vue or Nuxt project. The setup is quick, with features like keyboard controls, responsive layouts, and even advanced document options ready to go. For developers and teams, it’s a straightforward, reliable way to add rich PDF support to any Nuxt-powered app.

Disclaimer: I work at Vue PDF Viewer.

Why Choose @vue-pdf-viewer for Nuxt Applications

If you want smooth PDF handling in your Nuxt project, you need a component that just works. Vue PDF Viewer stands out for its balance of powerful features and simple setup. You can add the library into almost any Nuxt page or component with minimal setup. It's built for Nuxt and Vue, so you avoid heavy solutions or flaky workarounds.

Key Features that Set @vue-pdf-viewer Apart

Vue PDF Viewer offers everything most apps need right out of the box. Here’s what you get:

Smooth zoom and rotation: Users can view their PDFs up close, rotate pages, and not miss a detail.
Keyboard navigation: Move through documents without leaving the keyboard.
Responsive layouts: Fits devices big or small, so mobile users can scroll, zoom, and interact with ease.
PDF layers support: Support for text, canvas and annotation layers.
Search and text selection: Users find what they need fast, selecting and copying text directly from the PDF.
Easy customization: Vue PDF Viewer's toolbar or theme can be configured easily to fit your business needs.

If you want the full list, check the official documentation’s Feature Overview. You’ll see plenty of advanced options, but the defaults work for most projects.

Comparing @vue-pdf-viewer to Other Popular Alternatives

Several tools such as Apryse and Syncfusion compete in this space, but Vue PDF Viewer stands out for its simplicity and Vue-first design:

Vue-native: Compared to other PDF.js wrappers, Vue PDF Viewer is written entirely in Vue, which means fewer compatibility headaches.
Lightweight footprint: It’s lighter than some heavyweight tools like Apryse or Syncfusion.
Feature-rich yet accessible: While many open-source options lack advanced controls or built-in Nuxt support, Vue PDF Viewer gives you both out-of-the-box.

Where @vue-pdf-viewer Shines in Nuxt

You’ll see it in action everywhere—from simple PDF previews to interactive AI-powered PDF tools and full-fledged document management systems. It's a great fit for projects where:

✅ You need solid, bug-free PDF rendering.
✅ Custom UI or branding matters.
✅ Fast time-to-launch is key and the focus is on Vue or Nuxt development.

The component’s flexibility lets you scale from basic views to complex document tools without starting over each time.

Setting Up Your Nuxt Project for PDF Viewing

Getting your Nuxt project ready for PDF viewing starts with a solid foundation. You'll want installation to be smooth and straightforward asset handling to ensure reliable PDF rendering and easy file maintenance.

Install Dependencies and Project Scaffolding

Start by creating a new Nuxt application, or open your existing one.

Nuxt 3 (recommended):

Initialize your project:
- Run npx nuxi init my-nuxt-app to create a basic structure.
- Enter the project folder: cd my-nuxt-app.
- Install dependencies: npm install.
Add @vue-pdf-viewer:
- Install the package with npm install @vue-pdf-viewer.

Here’s a quick checklist before moving ahead:

Vue 3
Node 16+ for Nuxt 3

With your dependencies set, you’re ready to handle asset organization.

Configure Static Assets for PDF Files

How you store and serve your PDF files matters, especially when it comes to access speed and basic security. Nuxt 3 typically uses the public folder for this job, but there are a few gotchas to keep your files organized and safe.

In Nuxt 3, any files placed in the public folder are served from the root level. For example, a PDF saved as public/sample.pdf will be available at /sample.pdf in your browser.

Best practices for asset management:

Organize your PDFs in subfolders (e.g. public/pdfs/) if you plan to store more than a few documents.
Keep clear, consistent filenames and avoid spaces, use dashes or underscores.
Regularly clean out unused files to keep your build lightweight.

File access security:

Keep in mind that assets in public or static are publicly accessible. If you're dealing with sensitive or private PDFs, don't place them here. Instead:

Use authentication and store the files outside public
Serve them through a secure API or custom middleware.

Useful Resources

For more on how Nuxt handles public and static files, review the official assets documentation.
If you want a guide to help you decide where files belong or to understand asset handling differences, check out this breakdown on handling assets in Nuxt 3.
For quick comparisons on when to use each folder, see the Stack Overflow thread on Nuxt assets and static folders.

By planning where your PDFs live from the start, you avoid confusion later on—especially as your app grows. Keep things neat and protect anything sensitive, and your PDF workflow in Nuxt will stay smooth and manageable.

Integrating @vue-pdf-viewer in a Nuxt Component

With your Nuxt app set up and PDFs organized, the next step is to actually bring your PDF viewer to life. You have a few key choices here: create a self-contained component for on-demand use, wrap the viewer in client-only rendering to avoid SSR issues, or register it globally for reuse in bigger projects.

Here’s a step-by-step guide to each approach so you choose the one that fits your needs best.

📘 Related: You can also follow the official Nuxt setup guide in the documentation for a simpler quick-start example.

Creating a Reusable PDF Viewer Component

To start, it’s best to build a dedicated Vue component that handles all your PDF viewing logic. This keeps your code tidy and lets you drop the viewer anywhere in your app.

Here’s how you can do it:

Create a new file in your components folder. e.g. PdfViewer.vue
Import @vue-pdf-viewer/viewer and define your props.
Pass in the src prop, which is the path to your PDF file.
Optionally, add viewer options to customize controls or appearance.

Example code: components/PdfViewer.vue

<script setup>
import { ref } from 'vue'
import { VPdfViewer } from '@vue-pdf-viewer/viewer'

const pdfSrc = ref('/pdfs/sample.pdf') // or use a prop for dynamic paths
</script>

<template>
  <VPdfViewer :src="pdfSrc" />
</template>

This setup lets you easily update the source PDF or tweak viewer settings as needed. For more details about best practices with Vue components in Nuxt, check out the Nuxt components directory guide.

Client-Side Only Rendering with

Rendering PDF viewers on the server (SSR) can cause headaches since browser-specific APIs don’t exist during server-side rendering. Nuxt provides a simple fix with <ClientOnly> component in Nuxt 3.

How to use it:

In Nuxt 3, Wrap your PDF viewer like this:

<script setup>
import PdfViewer from './components/PdfViewer.vue'
</script>
<template>
 <ClientOnly>
  <PdfViewer />
 </ClientOnly>
</template>

What does this do?

<ClientOnly> tells Nuxt to delay rendering of your PDF viewer component until it's running in the browser. This prevents SSR-related errors from happening when browser-only code is accessed too early.

If you need a deeper explanation or run into issues, check out this discussion on Nuxt client-only plugins.

Using Nuxt Plugins for Global Registration

If your app needs to display PDFs in many places, it helps to register the viewer as a global component. Nuxt’s plugin system makes this smooth and keeps your code DRY (don’t repeat yourself).

Here’s the approach:

Create a new plugin file in plugins/vue-pdf-viewer.js (or .ts).
Import and register @vue-pdf-viewer globally.
In your Nuxt config, make sure the plugin is loaded only on the client.

Example for Nuxt 3:

// plugins/vue-pdf-viewer.client.js
import { defineNuxtPlugin } from '#app'
import { VPdfViewer } from '@vue-pdf-viewer/viewer'

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.component('VPdfViewer', VPdfViewer)
})

Nuxt automatically reads the files in the plugins/ directory and loads them at the creation of the Vue application. For full details, visit the Nuxt plugins directory documentation.

With the viewer globally registered, you can use <VPdfViewer /> anywhere in your project—no manual imports needed. This approach saves you from repetitive imports and keeps your codebase neat as your app scales.

Bonus Section: Styling Your PDF Viewer

Nobody wants a PDF viewer that looks out of place or breaks your app’s design flow. With a little effort, you can easily style @vue-pdf-viewer to match your branding.

Tips for styling:

Use CSS for visual tweaks: Adjust background colors, spacing, and toolbar icons by targeting the viewer’s CSS classes. For detailed steps and best practices, check out this resource on customizing CSS in PDF viewers.
Use Slots for custom controls: Vue’s slot system makes it easy to insert your own buttons or menus on the toolbar or sidebar.
Hide or reorder UI parts: Vue PDF Viewer toolbar can be toggled or reorganized through props or CSS. Keep only what you need on the screen.

Conclusion

Launching a PDF viewer in Nuxt with Vue PDF Viewer is fast and hassle-free. You get powerful display options, modern controls, and responsive layouts—ready to go with just a few steps. The component’s flexibility means you can start simple or customize for a tailored user experience.

🙏 Thanks for reading—if you’ve tried this in your own Nuxt app, please feel to share what you built or what you want to see next in Vue PDF Viewer.

I'm looking forward to seeing what you build with Vue PDF Viewer 🚀

What are PDF.js Layers and How You Can Use them in Vue.js

Kittisak Ma — Tue, 04 Mar 2025 08:00:00 +0000

PDF is everywhere, no matter what kind of web app you’re building, you’re bound to need a convenient PDF viewer at some point. But if you’ve ever tried to handle PDFs on the web, you know it can feel like wrestling with outdated plugins, iframe workaround or settling for awkward pop-ups.

That’s where PDF.js comes in—it's an open-source JavaScript library for rendering PDFs right in your browser. Now, if you’re like me and build apps in Vue.js, figuring out how to use PDF.js in your project can be tricky at first.

To leverage PDF.js's capabilities, it's important to understand its layered architecture. If you’ve ever wondered, “How do I enable text selection?” or “How do I handle links inside the PDF?” or even “How do I build advanced features like annotations?”, the answer usually lies in understanding these layers.

In this article, I’ll show you how PDF.js creates layers, what each layer is responsible for, and how you can apply them to your next Vue project. Let’s get going!

Vue PDF Viewer: Flexible and Powerful Vue.js PDF Component

Quick heads up on something I’ve been working on: Vue PDF Viewer, a handy PDF Viewer that renders PDFs right within your Vue or Nuxt app. It packs over 20 features, including out-of-the-box default toolbar, customization and responsive design, so your users never have to leave your site to interact with your documents.

If that sounds interesting, I’d love for you to give Vue PDF Viewer a try. Your support helps me keep creating awesome tools and tutorials like this one. ❤️

Overview of PDF.js Layers

Before we dive in, here’s a quick snapshot of the four major layers in PDF.js. Each layer handles a specific aspect of rendering or user interaction:

Canvas Layer: Render the static visual content of your PDF (shapes, images, text-as-graphics). It is the foundation of the PDF Viewer.
Text Layer: Sit on top of the canvas to ensure that text is selectable and searchable.
Annotation Layer: Handle interactive elements (links, forms, highlights) so users can click, type, or navigate.
Structural Layer: Manage the overall layout, including alignment and scaling for all the other layers.

By splitting different functionalities into distinct layers, PDF.js remains modular, efficient, and surprisingly easy to tweak.

Let’s start by creating a fresh Vue.js project to integrate PDF.js.

Set up Vue.js Project

In this article, I use Codepen as a code editor. If you want to follow along, you can create a new Pen on Codepen and follow the steps below.

Step 1: Pick a Vue Pen Template

The easiest way to get started is by using CodePen’s built-in Vue template. From the left menu, click on the Pen menu to open the options, then pick Vue Pen.

This gives you a pre-configured environment with a default Vue setup. In this interface, you can experiment with Vue codes and instantly see your results in the preview area.

Step 2: Configure the project and install PDF.js

Next, let’s configure your Vue project to use the pdfjs-dist library.

Open Settings: Click on the Settings button at the top of your Pen.
Select JS Options: In the popup, switch to the JS tab.
Pick Vue Version: Under Vue version, select Vue 3 (or whichever version fits your needs).
Add Packages: In the Add Packages box, search for and add pdfjs-dist.
Save and Close: Click Save & Close to apply your changes.

CodePen will automatically inject an import statement for pdfjs-dist into your code. You’ll typically want to move that statement below your <script> section to keep things clean and organized.

That’s it! You’re now set up to start experimenting with PDF.js layers within a Vue environment. So let us get to the layers.

1. Canvas Layer

Purpose

The Canvas Layer is the foundation—it’s where PDF.js draws the visual elements such as images, shapes, and text (as graphics). Essentially, what you see on-screen is coming from this layer.

How It Works

PDF.js uses the HTML <canvas> element to display the PDF's visual content
It utilizes the browser's 2D canvas API for high-performance rendering.
This means your PDF content will look consistent and accurate across various screen sizes and devices.

Use Cases

Ideal for non-interactive or static PDF content.
It renders the document as an image, ensuring PDF’s fonts, colors, and layouts are consistent across all devices.

Example of Canvas layer Code with Vue

Here’s a quick CodePen demo showcasing a minimal Canvas Layer setup in Vue.js.

📜 How the Code Works

Below, I’ll walk through the major steps for rendering a PDF page onto the canvas.

(1) Setting Up the PDF Worker

Before loading the PDF, we need to configure the PDF worker. The worker is responsible for processing the PDF in a separate thread, improving performance.

import * as PDFJS from "https://esm.sh/pdfjs-dist";
import * as PDFWorker from "https://esm.sh/pdfjs-dist/build/pdf.worker.min";

try {
  PDFJS.GlobalWorkerOptions.workerSrc = PDFWorker;
} catch (e) {
  window.pdfjsWorker = PDFWorker;
}

Explanation:

Here, we import pdf.worker.min.js and set it as the worker source.
The worker processes the PDF in a separate thread so our UI is not blocked.
If an error occurs, the worker is assigned to window.pdfjsWorker as a fallback

(2) Fetching and Loading the PDF

 const PDF_SRC = "https://pdfobject.com/pdf/pdf_open_parameters_acro8.pdf";
 export default {
  ...
  methods: {
    processLoadingTask(source) {
      const loadingTask = PDFJS.getDocument(source);
      loadingTask.promise
      .then(docProxy => ...)
      .then(page => {
         ...
         const renderContext = {
           canvasContext: context,
           viewport: viewport
         };
         return page.render(renderContext);
      })
    }
   },
   // Start the process when the component is mounted
   mounted() {
    this.processLoadingTask(PDF_SRC);
   }
 }

Explanation:

The processLoadingTask method initializes PDF loading via PDFJS.getDocument(source) from pdfjs-dist.
Once the PDF is fetched (from PDF_SRC), we store the document proxy (docProxy).
The total number of pages is determined and stored in totalPages.

(3) Rendering the Canvas Layer

Explanation:
After the PDF is loaded and we have a page object, the first page is extracted using getPage(1). PDF.js then:

Scales the canvas to match the PDF page dimensions.
A <canvas> element (canvasLayer) is used to render the PDF page as an image.
The rendering process is handled by page.render(renderContext), where canvasContext paints the page content onto the canvas.

This ensures the final output accurately matches the original PDF’s appearance.

2. Text Layer

Purpose

How It Works

PDF.js extracts the text content separately from the PDF.
It positions each piece of text exactly over the underlying canvas, using absolutely positioned <div> elements.
Even though you might not see these text <div> visually (they’re often transparent), they’re there to support selection and searching.

Use Cases

Enable text selection and copying from the PDF.
Text layer is crucial for accessibility, as it enables screen readers to interpret the content.
Provide text searching and highlighting within the PDF viewer.
Keep the text aligned with the rendered PDF page

Text layer Code Example

Here’s a Vue.js CodePen example that demonstrates a Text Layer in action:

📜 How the Code Works

(1) Structuring the Layers

<div ref="pdfLayersWrapper" class="pdf__layers">
  <div class="pdf__canvas-layer">
    <canvas ref="canvasLayer" />
  </div>
  <div ref="textLayer" class="pdf__text-layer"></div>
</div>

Explanation:

The pdfLayersWrapper is a container that holds both the Canvas Layer and the Text Layer.
The Canvas Layer (canvasLayer) displays the PDF page visually.
The Text Layer (textLayer) sits on top of the canvas, allowing text selection.

(2) Fetching and Loading the PDF

(Identical to the steps in the Canvas Layer—we load the PDF document first.)

(3) Rendering the Text Layer

renderText(pdfPageProxy, textLayerContainer, viewport) {
  ...
  pdfPageProxy
    .getTextContent()
    .then((content) => {
      const renderTask = new PDFJS.TextLayer({
        container: textLayerContainer,
        textContentSource: content,
        viewport: viewport.clone({ dontFlip: true })
      });
      return renderTask.render();
    });
 },
 processLoadingTask (source) {
  ...
  this.renderText(...)
 }

Explanation:

Render the text layer (this.renderText()).
pdfPageProxy.getTextContent() retrieves the text data from the PDF page.
This data is passed into a new TextLayer, specifying:
- container: Container where text is rendered.
- textContentSource: Extract text data from the PDF.
- viewport: Define text positioning and scaling.
renderTask.render() places invisible but selectable text <div> over the canvas.

3. Annotation Layer

Purpose

How It Works

PDF.js extracts annotation data (links, form fields, etc.) from the PDF.
It overlays these data as interactive HTML elements (e.g. <a>, <input>, <textarea>), which sit above the Canvas Layer and Text Layer positioned using CSS.
This layer ensures that users can click, type, and interact without altering the PDF’s static visuals.

Use Cases

Clicking on links within PDF to navigate between pages.
Rendering highlights, underlines, and notes from PDF annotations.
Displaying interactive form fields within a PDF.

Annotation layer Code Example

Check out this CodePen example on the Annotation Layer for Vue.js:

You can click the links inside the Codepen to change the PDF's page.

📜 How the Code Works

(1) Structuring the Layers

<div ref="pdfLayersWrapper" class="pdf__layers">
  <div class="pdf__canvas-layer">
    <canvas ref="canvasLayer" />
  </div>
  <div ref="textLayer" class="pdf__text-layer"></div>
  <div ref="annotationLayer" class="pdf__annotation-layer"></div>
</div>

Explanation:

We add another <div> for the Annotation Layer within pdfLayersWrapper.
The Annotation Layer is positioned on top of the Canvas Layer and Text Layer.

(2) Fetching and Loading the PDF

(Again, the same initial PDF loading steps as before.)

(3) Rendering the Annotation Layer

 async getAnnotations(pageProxy) {
  const annotations = await pageProxy.getAnnotations({ intent: "display" });
  return annotations;
 },
 async renderAnnotations(pdfPageProxy, annotationLayerContainer, viewport) {
   const annotations = await this.getAnnotations(pdfPageProxy);
   ...
   const annotationLayer = new PDFJS.AnnotationLayer({
    div: annotationLayerContainer,
    viewport: clonedViewport,
    page: pdfPageProxy
  });
  await annotationLayer.render({
    ...,
    annotations,
    linkService: new SimpleLinkService(),
    ...
  })
 }

Explanation:

getAnnotations retrieves all annotation info from the PDF page (links, form fields, etc.).
We clone the viewport to match the page’s dimensions for correct positioning.
renderAnnotations is then called to replace existing elements in annotationLayerContainer before rendering new ones. It does so by:
- Creating a new AnnotationLayer instance to manage and render annotation elements.
- Displaying the annotation layer by annotationLayer.render({...}), passing in the annotations and SimpleLinkService() to handle internal PDF links.

(4) Handling Internal Link Clicks

...
annotationLayerContainer.addEventListener("click", async (event) => {
  ...
  const annotationLinkId = annotations.find((ele) => ele.id === id);
  ...
  const pageIndex = await this.pdfDocProxy.getPageIndex(
    annotationLinkId.dest[0]
  );
  this.currentPage = pageIndex + 1;
});

Explanation:

When a user clicks on a link inside the PDF, the event checks if it's an annotation.
If it is, we look up the destination page by getPageIndex() and see if it points to a different page in the PDF.
We then navigate to that page by updating this.currentPage.

(5) Handling Page Navigation

A simple navigation bar lets users switch between pages.

 <div class="page-navigation">
  <button :disabled="currentPage <= 1" @click="--currentPage">
   &larr; 
  </button>
  <span>{{ currentPage }}/{{ totalPages }}</span>
  <button :disabled="currentPage >= totalPages" @click="++currentPage">
   &rarr;
  </button>
 </div>

Explanation:

The currentPage value updates when navigation buttons are clicked.
watch: { currentPage(newValue) { ... } } ensures that all layers are re-rendered when the page changes.
This ensures all layers—Canvas, Text, and Annotation—stay in sync.

4. Structural Layer

Purpose

This layer is a must-have when creating a PDF viewer as it serves as the foundation that glues all other layers together.

How It Works

The Structural Layer is typically implemented by a container element (<div>) that wraps all other layers.
Maintain consistent positioning among layers so they don’t drift apart during zooms or scrolls.
Act as the foundation that ties everything together, so your PDF viewer remains cohesive.

Use Cases

Ensure a consistent user experience across different screen sizes and resolutions.
Enable smooth zooming by scaling all layers proportionally.
Centralize navigation and layout logic (e.g. controlling how the viewer scrolls from one page to another.)

In our code examples, the <div ref="pdfLayersWrapper" class="pdf__layers"> element serves as the Structural Layer, wrapping for other layers:

<div ref="pdfLayersWrapper" class="pdf__layers">
  <div class="pdf__canvas-layer">
    <canvas ref="canvasLayer" />
  </div>
  <div ref="textLayer" class="pdf__text-layer"></div>
  <div ref="annotationLayer" class="pdf__annotation-layer"></div>
</div>

Why is this important?

The Structural Layer wrapper ensures the Canvas, Text, and Annotation Layers all stay in sync, even when you zoom or flip through pages.
You can customize the wrapper to handle special behaviors like lazy-loading pages, scroll snapping and other performance optimizations.

How Layers Work Together

Here’s how all four layers in PDF.js work together in harmony:

Rendering Process:
Each page is first drawn onto the Canvas Layer (visual content). Next, the Text Layer is layered on top to enable selection and searching. Finally, the Annotation Layer is placed at the very top, providing interactive elements like links and form fields.
Interactivity:
The Annotation Layer handles user events (like clicking on links or typing into form fields), while the Text Layer ensures text can be highlighted, copied, or searched.
PDF Viewer:
The Structural Layer wraps everything up, ensuring that zooming, resizing, and navigation across pages remain consistent. It keeps all layers aligned and responsive, so users get a polished viewing experience.

Conclusion

I’ve used PDF.js in a variety of Vue.js projects, from simple PDF previews to fully interactive document systems, the layered architecture is always at the core.

Why does this matter for you?

You can optimize each layer for performance or user experience.
You can customize how your viewer handles interactions, text searches, or forms.
You’ll find it much easier to maintain or extend your PDF viewer code.

By understanding these layers, you will be able to optimize PDF.js implementations, customize features, and deliver a better user experience. Whether you’re building a simple Vue.js PDF viewer or a complex document management system, leveraging these layers effectively will set your project up for success.

Vue PDF Viewer: The PDF Viewer Built for Vue.js Developers 🚀

If you enjoyed this article, I’d love for you to check out Vue PDF Viewer. It’s a PDF Viewer built from the ground up for Vue and Nuxt applications. Whether you’re just starting out or already running a large-scale app, Vue PDF Viewer got you covered.

Designed with developers in mind, Vue PDF Viewer offers:

Simple Vue integration to get you up and running fast.
Advanced customization so you can nail that perfect look and feel.
Responsive layouts that adapt to any device.
Developer-friendly APIs for more flexibility.

Your support motivates me to keep creating tools and content for the Vue community. Thank you for checking out Vue PDF Viewer. Happy coding! 🙏

Best 4 Methods to Build a PDF Viewer in React.js: PDF.js, react-pdf, and More (2024 Guide) 🚀

Kittisak Ma — Wed, 23 Oct 2024 07:33:41 +0000

When working on React projects, one thing I’ve learned is that having the right tools can make or break the user experience. And when it comes to displaying documents, PDFs are still one of the best ways to share content, whether it’s reports, manuals, or e-books. The challenge, though, is how to integrate a reliable PDF viewer into your app without jumping through hoops.

In this article, I’ll walk you through four different ways to build a PDF viewer in React.js. From quick and simple methods like iFrame and opening PDFs in a new tab, to more customizable options like PDF.js and react-pdf—you’ll be able to choose the approach that works best for your project.

Why PDFs Matter in Web Development

Rendering PDFs on websites comes with a wide range of use cases. Here are some scenarios where PDFs can really come in handy:

Financial Reports
Imagine you’re building a finance dashboard, and your users need to access quarterly reports or balance sheets. By embedding these documents as PDFs, users can easily download, print, or view them in high resolution on any device. Plus, you keep the formatting consistent and professional, making sure nothing looks out of place.
Sales Invoices
For apps that generate or display invoices, PDFs are the perfect format to ensure clarity and accuracy. You can provide users with downloadable, printable invoices that maintain the exact layout and branding you’ve designed. No more worrying about documents being altered or misinterpreted.
Research Papers
If you’re working on a platform that handles academic content or research, PDFs are a great way to present papers, journal articles, and white papers. Researchers can zoom in for detail, highlight key points, or leave annotations—all while preserving the document’s original format.
Legal Contracts
For businesses dealing with contracts, confidentiality agreements, or any legal documents, PDFs are essential for maintaining integrity and security. PDFs ensure that legal contracts remain tamper-proof, preserving the original formatting and allowing for secure digital signatures. This is crucial when handling sensitive agreements, ensuring they can be easily shared, viewed, and stored by all parties involved without the risk of edits.

React PDF: A Flexible and Powerful PDF Viewer for React.js

Before diving into the technical side of things, let me introduce you to React PDF—a library I’ve been working on that brings PDF viewing directly into your React or Next.js applications. With over 20 features including theme customization, external APIs, and responsive layouts, it’s perfect for ensuring your users can interact with PDFs without leaving your site.

If you’re interested in trying it out, I’d be super grateful if you could check out React PDF. Your support will motivate me to keep creating more content! ❤️‍🔥

Method 1: Open PDF in a New Tab

If you're working in React and need a simple way to open PDFs, Method 1 is your go-to solution: opening the PDF in a new browser tab. Let's break it down:

1. Add a Link or Button

In your React component, create a link or button to open the PDF.

<a href="/your-pdf.pdf" id="pdfLink" target="_blank">Open PDF</a>
<!-- or button -->
<button id="pdf-button">Open PDF</button>

2. Trigger the PDF

Add an onclick event to open the PDF in a new tab.

const pdfUrl = '/your-pdf-url-goes-here.pdf';

document.getElementById('pdf-button').onclick = function() {
    window.open(pdfUrl, '_blank');
};

Pros and Cons

Pros:

Easy to Implement: This method is quick and simple.
Direct Access: Users can view the PDF without anything in between.

Cons:

Limited Control: You can't fully control how the PDF is displayed.
Browser Differences: The way it behaves can vary between browsers.

When to Use It

Use this method when you want to keep the PDF viewer separate from your main website. For instance, if embedding it in an iframe isn't ideal.

Method 2: Using an iFrame, Embed, or Object

A simple way to display PDFs in React is by using an <iframe>, <embed>, or <object> element. These methods leverage the browser’s built-in PDF capabilities, allowing you to embed the PDF directly into your app.

How to Implement:

Create your React project.
Add one of these elements (<iframe>, <embed>, or <object>) in your JSX.
Set the src attribute to the PDF file’s URL.

`<iframe>` Example:

<iframe src="/your-pdf-url.pdf" width="100%" height="600px"></iframe>

`<embed>` Example:

<embed src="/your-pdf-url.pdf" width="100%" height="600px" type="application/pdf" />

`<object>` Example:

<object data="/your-pdf-url.pdf" width="100%" height="600px" type="application/pdf">
  <p>Your browser doesn’t support PDFs. Please download the PDF to view it: <a href="/your-pdf-url.pdf">Download PDF</a>.</p>
</object>

You can see a React code in my Github repository

Pros:

Super Easy: It’s quick and simple to implement.
Uses Browser’s PDF Viewer: No extra libraries required—just use the browser’s native PDF viewer.
No Setup Needed: Works right away without additional configuration.

Cons:

Limited Control: You can’t control the PDF viewer’s interface or customize it.
Browser Compatibility: Not all browsers handle these methods the same way.
Customization Limits: These options don't offer much flexibility for customizing the viewing experience.

When to Use It:

Use these methods when you want a fast, straightforward solution and don’t need to customize the PDF viewer.

Method 3: Using PDF.js

If you need more control over how PDFs are displayed and interacted with, PDF.js is a great option. Created by Mozilla, PDF.js lets you fully customize the PDF viewing experience within your app.

How to Implement:

Install the PDF.js library in React project.

npm install pdfjs-dist

Create a React component to render the PDF using PDF.js.

import { PdfProps } from "../types";
import * as PDFJS from "pdfjs-dist";
import type {
  PDFDocumentProxy,
  RenderParameters,
} from "pdfjs-dist/types/src/display/api";
import { useCallback, useRef, useState, useEffect } from "react";

export default function PdfJs(props: PdfProps) {
  PDFJS.GlobalWorkerOptions.workerSrc =
    "https://unpkg.com/pdfjs-dist@4.7.76/build/pdf.worker.min.mjs";

  const { src } = props;
  const canvasRef = useRef<HTMLCanvasElement>(null);

  const [pdfDoc, setPdfDoc] = useState<PDFDocumentProxy>();
  const [currentPage, setCurrentPage] = useState(1);
  let renderTask: PDFJS.RenderTask;

  const renderPage = useCallback(
    (pageNum: number, pdf = pdfDoc) => {
      const canvas = canvasRef.current;
      if (!canvas || !pdf) return;
      canvas.height = 0;
      canvas.width = 0;
      // canvas.hidden = true;
      pdf
        .getPage(pageNum)
        .then((page) => {
          const viewport = page.getViewport({ scale: 1.5 });
          canvas.height = viewport.height;
          canvas.width = viewport.width;
          const renderContext: RenderParameters = {
            canvasContext: canvas.getContext("2d")!,
            viewport: viewport,
          };
          try {
            if (renderTask) {
              renderTask.cancel();
            }
            renderTask = page.render(renderContext);
            return renderTask.promise;
          } catch (error) {}
        })
        .catch((error) => console.log(error));
    },
    [pdfDoc]
  );

  useEffect(() => {
    renderPage(currentPage, pdfDoc);
  }, [pdfDoc, currentPage, renderPage]);

  useEffect(() => {
    const loadingTask = PDFJS.getDocument(src);
    loadingTask.promise.then(
      (loadedDoc) => {
        setPdfDoc(loadedDoc);
      },
      (error) => {
        console.error(error);
      }
    );
  }, [src]);

  const nextPage = () =>
    pdfDoc && currentPage < pdfDoc.numPages && setCurrentPage(currentPage + 1);

  const prevPage = () => currentPage > 1 && setCurrentPage(currentPage - 1);

  return (
    <div>
      <button onClick={prevPage} disabled={currentPage <= 1}>
        Previous
      </button>
      <button
        onClick={nextPage}
        disabled={currentPage >= (pdfDoc?.numPages ?? -1)}
      >
        Next
      </button>
      <canvas ref={canvasRef}></canvas>
    </div>
  );
}

You can find a complete example code on my Github: components/PdfJs.tsx.

Here is the result 👇

Pros:

Advanced Features: PDF.js provides powerful PDF rendering with options like zoom, page navigation, and more.
Highly Customizable: You have full control over how the PDF is displayed and interacted with.
Cross-Browser Support: Works across most modern browsers.
Well-Maintained: Backed by a big community with regular updates.

Cons:

Learning Curve: It takes time to learn and implement.
More Complex: Setting it up is harder compared to using iFrame or opening PDFs in a new tab.
Documentation Challenges: The docs can be tough to follow.
Integration Issues: Customizing it for frameworks like React, Angular, or Vue can be tricky.
Higher Complexity: Handling advanced interactions with PDFs increases the complexity.

When to Use It:

Use PDF.js when you need full control over the PDF viewer and want to add advanced features directly into your app’s interface.

Method 4: Using react-pdf (MIT)

react-pdf is an open-source package built on top of PDF.js that makes it easier to display PDFs in React apps while simplifying the development process.

How to Implement:

Install react-pdf using npm or yarn.

npm install react-pdf

Import the react-pdf component into your app.

import { pdfjs } from "react-pdf";

pdfjs.GlobalWorkerOptions.workerSrc = `//unpkg.com/pdfjs-dist@${pdfjs.version}/build/pdf.worker.min.mjs`;

Follow the instructions on GitHub for detailed setup.
Create a React component to render PDF

export default function PdfReactPdf({ src }: PdfProps) {
  const [numPages, setNumPages] = useState<number>();
  const [pageNumber, setPageNumber] = useState<number>(1);

  function onDocumentLoadSuccess({ numPages }: { numPages: number }): void {
    setNumPages(numPages);
  }

  function nextPage() {
    setPageNumber((v) => ++v);
  }

  function prevPage() {
    setPageNumber((v) => --v);
  }

  return (
    <div style={{ width: "100%", height: "100%" }}>
      <button onClick={prevPage} disabled={pageNumber <= 1}>
        Previous
      </button>
      <button onClick={nextPage} disabled={pageNumber >= (numPages ?? -1)}>
        Next
      </button>
      <Document
        file={src}
        onLoadSuccess={onDocumentLoadSuccess}
        className="my-react-pdf"
      >
        <Page pageNumber={pageNumber} />
      </Document>
      <p>
        Page {pageNumber} of {numPages}
      </p>
    </div>
  );
}

You can check out my example on my Github: components/PdfReactPdf.tsx.

Pros:

Easy Integration: Works smoothly with React. Better developer documentation compared to PDF.js.
More Control: Offers more customization than iFrame or New Tab methods.
Responsive and Customizable: Adjusts well to different screen sizes and offers some customization.

Cons:

More Setup: Takes a bit more effort to set up compared to simpler methods.
Limited Advanced Features: Doesn’t offer as much flexibility as using the full PDF.js library.

When to Use It:

Use react-pdf if you need an easy-to-implement, customizable PDF viewer for your React project.

Conclusion

There are several ways to implement a PDF viewer in React.js. Using iFrame or opening the PDF in a new tab offers simplicity but limits customization. PDF.js provides advanced features and control, but it comes with added complexity. react-pdf (open-source) bridges the gap by offering ease of use with customization options.

Choose the method that best fits your project’s needs, whether it’s speed, simplicity, or control over the user experience.

Is there a Better Solution?

While methods like iFrame or opening PDFs in a new tab can be quick fixes, they don’t offer much control or customization. PDF.js and react-pdf (an open-source library for React) provide more advanced options, but they come with their own challenges—especially if you’re looking for something easier to implement, maintain, and customize for your specific React project.

That’s why I’m building React PDF (not to be confused with react-pdf). While react-pdf is a great open-source library, React PDF is designed to offer more flexibility, powerful customization options, and a simpler setup process tailored to developers working on both small and complex React applications.

Made for React.js: Unlike more general libraries, React PDF is built from the ground up to work seamlessly with React. Whether you need quick rendering or advanced features, it integrates easily into your project with just a few lines of code.
Customization without Complexity: With React PDF, you have full control over the appearance and behavior of your PDF viewer. You can match the viewer’s design to your app’s theme, add interactive features like search and bookmarking, and customize the layout—all without the hassle of dealing with complex configurations.
Extensive Feature Set: Whether you need basic functionality like viewing PDFs or more advanced features like rotation, different scrolling modes, and responsive design, React PDF has you covered. Plus, it’s built with performance in mind, so you don’t have to worry about lag when handling large files.
User-Friendly Documentation: I’ve made sure the technical docs are clear and easy to follow. From starter kits to detailed API references, everything is in place to help you get up and running fast.
Reliable Support and Updates: As developers, I know how important it is to have reliable support. That’s why React PDF comes with responsive customer support and regular updates to keep the library optimized and bug-free.

If this sounds like what you need, I’d be grateful if you could check out React PDF. Your support encourages me to keep improving and building tools for the community. Thank you! 🙏

MUI Date Picker Showdown: Community vs. Pro version

Kittisak Ma — Thu, 11 Apr 2024 12:30:00 +0000

As a developer, I find Material-UI (MUI) to be an absolute gem in the React ecosystem. When I embark on a new web application project or need to create sleek and functional interfaces, it’s my go-to toolkit. MUI is like a trusty companion that walks alongside me.

Inspired by Google’s Material Design, it brings a sense of consistency and modernity to my projects, no matter the platform. The pre-built components in MUI are like building blocks. They save me precious time — time that I’d rather spend sipping coffee and brainstorming creative solutions. Whether I am crafting a complex enterprise app or a single-page site, MUI has my back.

Among its many components, the Date Picker stands out as an essential tool for applications that requires date selections. It is offered in both the Community and Pro versions of MUI X, with the Pro version offering unique features and capabilities over the Community version. But which one is the best fit for your project? Let's dive into the MUI Date Picker showdown: Community vs. Pro.

Community Edition: The Open-Source Hero

The Community version of the MUI Date Picker is a go-to choice for developers looking for a free and reliable solution. It offers basic date picking functionalities like selecting dates from a calendar or inputting them through a text field.

Key Features:

Basic Date Selection: Allows users to select and input a single date, single time or single date & time, facilitating basic scheduling and planning functionalities.
Seamless Integration: Can be easily integrated into any React application, offering a straightforward setup process.
Customization and Theming: Provides standard customization options that adhere to Material Design principles, ensuring a consistent look and feel across your application.

To further elaborate, the Community version comes with the following components:

Date Components: These comprise a date picker, a date field for simple date selection and a date calendar to display.
Date Picker, Mobile Date Picker and Date Field

Date Calendar
Time Components: Included here are a time picker and a time field, facilitating time selection processes.

Time Picker, Mobile Time Picker and Time Field
Date-Time Components: The version comes with a date-time picker and a date-time field, enabling selection and display of both date and time simultaneously.

Date Time Picker, Mobile Date Time Picker and Date time Field

The Community version is perfectly suited for small to medium-scale projects that strictly follow the Material UI design system, requiring basic date picking functionalities within budget constraints.

Pro Version: Elevating Date Range Selection

For developers seeking more advanced features and dedicated support, the Pro version of MUI X Date Picker offers additional features on top of all the features included in the Community version:

Key Features:

Date and Time Range Selection: In addition to basic date picking, the Pro version offers a date/time range selector, allowing users to make precise time selections within a specified range.
Dedicated Support: Subscribers to the Pro version gain access to MUI's dedicated support team for troubleshooting and guidance.

Comparing MUI X Plans

When considering the Pro plan for MUI X, it’s essential to weigh your specific requirements against the plan’s offerings. Sure, it nails the date-time range features, but it’s also got a secret stash of UI magic.

The Pro plan not only caters to date-time functionalities but also provides a comprehensive suite of advanced UI components. These include powerful libraries like the advanced data grid and other enhancements. It’s tailor-made for developers and projects seeking a robust set of features and robust support.

However, if your project’s focus primarily revolves around sophisticated date-time management, you might want to explore alternative solutions or carefully evaluate whether the Pro plan’s broader offerings align with your needs and budget.

Conclusion

The choice between MUI Date Picker Community and Pro versions ultimately hinges on your project's specific needs and budget constraints. For developers working on smaller projects or those with limited requirements for date selection, the Community version offers a robust, cost-effective solution. On the other hand, the Pro version is best suited for enterprise-level applications or large projects demanding a wider range of functionalities, customization options, and global support.

Regardless of your choice, both versions uphold the high standards and aesthetic appeal synonymous with Material-UI components. By comparing the two, developers can make an informed decision that best suits their project, ensuring a sleek and efficient user experience.

Is There a Better Solution?

With MUI X Pro’s high cost, developers seeking budget-friendly date/time pickers often face a dilemma. While building custom solutions or using other libraries is an option, seamless integration with MUI can be tricky. To bridge this gap, I’m developing MUI Table Date, a cost-effective alternative that combines functionality with ease of use.

When comparing MUI Table Date to MUI X, several factors make it a compelling alternative:

Cost-Effective: MUI Table Date is 81% cheaper than MUI X Pro. If you're looking for a wallet-friendly option without compromising functionality, it's a definite win.
Feature-Rich: Don't let the price fool you. MUI Table Date packs a punch with advanced features such as Date Time Range Picker and advanced data grids.
Simple Licensing: No convoluted terms here. MUI Table Date keeps it straightforward. No legal acrobatics – just clear licensing.
Seamless Integration: Worried about compatibility? Fear not! MUI Data Table plays well with MUI. It's like they were made for each other.

If you find this library helpful, please consider exploring MUI Table Date. Your support motivates me to create even more content. Thank you in advance! 🙏

📝 Using JS Object Schemas to Validate Data with Yup, Zod, Joi and more 🤩

Kittisak Ma — Tue, 26 Mar 2024 13:30:00 +0000

I’m sure many of you who have developed interactive web applications have experience handling data validation. In fact, it’s probably a common topic. You could create custom validations or you may choose to validate via JavaScript Object Notation (JSON) Schemas . When I need to use JSON Schema library, I tend to use Yup. Having validate data with JSON Schema libraries and without one across different project scales, they are effective in their own ways.

Today, I want to dive deeper into the world of JSON, exploring popular libraries as well as other notable libraries in the ecosystem. Additionally, I will mention how you can do custom validations without using a JSON Schema library. And finally, I will compare both methods.

Please note that I’m using code examples using JavaScript without basing on a JS framework such as React or Vue since you can apply both methods to any JS framework.

Validex: The Most Complete Validation Collection for React Forms

Just a quick background about what I'm working on. Validex can help you validate React forms in minutes. It has over 36 validators ranging from string, password, credit card, email, file, image and more. Each validator has TypeScript and JavaScript codes, RegEx and Non-RegEx options and unit tests.

I would be grateful 🥹 if you could take a moment to explore Validex out. It would motivate me to create even more contents.

What is JavaScript Object Notation Schema?

JSON Schemas define the structure and validation rules for JavaScript objects. They provide a way to specify the expected shape of an object and enforce validation rules on its properties. This helps ensure that data is in the correct format and meets certain criteria.

Object schemas can be particularly useful in scenarios where user input needs to be validated before it is processed. For example, validating user registration forms, API request payloads, or form fields in a web application.

Introducing Yup and Zod

Yup and Zod are two popular libraries in the JavaScript ecosystem that provide powerful and flexible schema validation capabilities. Both libraries offer rich features and strong type support, making them ideal choices when working with TypeScript.

Yup

Yup is a schema validation library that focuses on simplicity and ease of use. It provides a fluent API for defining object schemas and supports a wide range of validation rules out of the box. With Yup, you can easily define schema validation rules such as required fields, minimum and maximum values, regular expressions, and more.

Yup also supports asynchronous validation, allowing you to validate data against external data sources or perform complex validation logic. It also integrates well with popular frontend frameworks like React, making it a versatile choice for both server-side and client-side validation.

Zod

Zod is another powerful schema validation library for JavaScript and TypeScript. It takes a pragmatic approach to validation and aims to provide a seamless development experience. Zod's API is inspired by Yup but comes with some unique features and optimizations.

With Zod, you can define complex object schemas with ease. It supports various validation rules and provides a robust type inference system that ensures type safety throughout your codebase. Zod also includes features like partial and pick helpers, allowing you to create more flexible validation schemas.

Other Libraries in the Ecosystem

While Yup and Zod are popular choices, there are several other libraries available in the JavaScript ecosystem for schema validation. Some of these include:

Joi: Joi is a powerful schema validation library that focuses on server-side validation. It provides a comprehensive rule set and supports complex validation scenarios.
Ajv: Ajv is a fast and powerful JSON Schema validator that supports a wide range of validation keywords and features. It is highly extensible and widely used in the JavaScript community.
Superstruct: Superstruct is a lightweight and minimalist validation library that leverages TypeScript's powerful typesystem to provide compile-time validation.

These libraries offer different features and tradeoffs, so exploring the options and choosing the one that best fits your needs is recommended.

How to Utilize Each Library in a Customized Manner

In this section, I will explore how to implement custom email validation using libraries such as Yup, Zod, and other popular options like Joi and Ajv. Email validation is a common requirement in many applications, and different libraries offer different approaches and features to handle this task. Let's dive into the examples and explore how each library can be used to validate email addresses in a customized manner.

Email Validation Rules

Here are some commonly used email validation rules that I will be incorporating in the examples:

Email is required: The email field must not be empty or null.
Email must include @ symbol: The email address should contain the "@" symbol.
Email must include the domain: The email address should include the domain name (e.g., example.com).
Email must include the top-level domain: The email address should have a valid top-level domain (e.g., .com, .org, .net).

Yup

For an email validation, Yup will use string and test methods to create custom validation. Here is an example.

import { object, string } from "yup";
const formSchema = object({
  email: string()
    .required("Please provide an email address")
    .test("email-symbol", "Please include an `@` symbol", (value) => {
      return value.includes("@");
    })
    .test("email-domain", "Please provide an email's domain", (value) => {
      return /@[a-zA-Z]{2,}/gi.test(value);
    })
    .test(
      "email-top-level-domain",
      "Please include top level domain such as .co .org",
      (value) => {
        return /\.[a-zA-Z]{2,}$/gi.test(value);
      }
    )
    .test("email-format", "Invalid email format", (value) => {
      const emailRegex = /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i;
      return emailRegex.test(value);
    })
});
...

You may find the codes in this CodePen link.

Zod

Zod will use string and refine methods to create custom validation

import { z } from "zod";

const formSchema = z.object({
  email: z
    .string()
    .refine(
      (val) => !!val,
      () => {
        return {
          message: "Please provide an email address"
        };
      }
    )
    .refine((val) => val.includes("@"), {
      message: "Please include an `@` symbol"
    })
    .refine((val) => /@[a-zA-Z]{2,}/gi.test(val), {
      message: "Please provide an email's domain"
    })
    .refine((val) => /\.[a-zA-Z]{2,}$/gi.test(val), {
      message: "Please include top level domain such as .co .org"
    })
});

CodePen link of Zod validation.

Joi

Joi will use any and custom methods to create non-primitive data validation.

import Joi from "joi";

const validateEmailFn: Joi.CustomValidator<string> = (value, helpers) => {
  console.log("validateEmail", value);
  if (!value) {
    return helpers.message("Please provide an email address");
  }
  if (!value.includes("@")) {
    return helpers.message("Please include an `@` symbol");
  }
  if (!/@[a-zA-Z]{2,}/gi.test(value)) {
    return helpers.message("Please provide an email's domain");
  }
  if (!/\.[a-zA-Z]{2,}$/gi.test(value)) {
    return helpers.message("Please include top level domain such as .co .org");
  }
  return value;
};

const { object, string } = Joi.types();
const formSchema = object.keys({
  email: Joi.any().custom(validateEmailFn, "test")
});

CodePen link of custom email validation with Joi.

Ajv

For Ajv, you have to use addKeyword method with code, compile or validate properties to custom how to validate your JSON schema. Referring to its documentation, I have created an example with validate property.

import Ajv, { ErrorObject, JSONSchemaType } from "https://esm.sh/ajv";
interface Form {
  email: string;
}
// Create an instance of Ajv
const ajv = new Ajv({ allErrors: true });
ajv.addKeyword({
  keyword: 'emailFormat',
  type: 'string',
  errors: true,
  validate:
    function customValidate(schema: boolean, value: string) {
      let message = '';
      if (!value) {
        message = 'Please provide an email address';
      } else if (!value.includes('@')) {
        message = 'Please include an `@` symbol';
      } else if (!/@[a-zA-Z]{2,}/gi.test(value)) {
        message = 'Please provide an email\'s domain';
      } else if (!/\.[a-zA-Z]{2,}$/gi.test(value)) {
        message = 'Please include top level domain such as .co .org';
      } else {
        return true
      }
      customValidate.errors = [{keyword: 'emailFormat', message}];
        // Use a regular expression to validate email format
        // const emailRegex = /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i;
        // return emailRegex.test(value);
      return false;
    },
})
const formSchema: JSONSchemaType<Form> = {
  type: "object",
  properties: {
    email: {
      type: "string",
      emailFormat: true
    }
  },
};
// Compile the schema
const validate = ajv.compile(formSchema);

This shows Ajv custom validation without ajv-formats. CodePen link

Custom Validation Without JSON Schema Libraries

When it comes to data validation, an alternative approach to using JSON schema libraries is to implement custom validation logic. This involves writing code specifically tailored to validate the data based on the requirements and constraints of the application. Here is the example of the Email validation without any JSON schema library.

import { debounce } from 'https://codepen.io/9haroon/pen/GRLgddJ.js';

function validateEmail(email: string) {
  if (!email) {
    return { message: 'Please provide an email address' }
  }
  if (!email.includes('@')) {
    return { message: 'Please include an `@` symbol' }
  }
  if (!(/@[a-zA-Z]{2,}/gi.test(email))) {
    return { message: 'Please provide an email\'s domain' }
  }
  if (!(/\.[a-zA-Z]{2,}$/gi.test(email))) {
    return { message: 'Please include top level domain such as .co .org' }
  }
  return { message: null }
}

const form = document.querySelector("#form");
const errorElem = document.querySelector("#form > p");
const emailElem = document.querySelector('[name="email"]');

const submitCallback = (event) => {
  console.log('Start Validation')
  errorElem.innerHTML = "";
  const { message } = validateEmail(emailElem.value)
  if (message) {
    errorElem.innerHTML = message;
  }
};

form.addEventListener("submit", submitCallback, false);
emailElem.addEventListener("input", debounce(submitCallback, 500), false);

The codes has an event listeners for the form submission event and the email input event. When the form is submitted, the submitCallback function is executed. Similarly, when the user inputs text in the email field, the submitCallback function is executed after a debounce of 500 milliseconds (to prevent rapid validation). In submitCallback function. It clears any previous error messages, calls the validateEmail function to validate the email value entered by the user, and displays the error message (if any) in the errorElem element.

Here is the CodePen link. Feel free to explore it further.

Comparing Using V. Without JSON Schema Libraries

Based on various technical factors, I have made a side by side comparison summary below:

Aspect	Using JSON Schema Libraries	Without Using JSON Schema Libraries
Standardized Schema Definition	Provide a standardized way to define schemas for data validation	Require manual implementation of validation logic without a standard schema format
Validation Features	Offer a wide range of validation features	Need to be implemented for each validation requirement
Schema Reusability	Can be reused across the application or in other projects	May not be easily reusable and may result in code duplication
Data Integrity	Enforce validation rules to ensure only valid data is accepted	Rely on discipline to maintain data integrity through custom validation logic
Learning Curve	Require time and effort to learn the syntax and best practices of the library	Require understanding of JSON schemas and validation rules
Dependency Management	Add a new dependency that needs to be managed and updated	No additional dependencies
Performance Overhead	May introduce performance overhead based on validation complexity and data size	Can be optimized for specific requirements to potentially reduce performance overhead
Flexibility	Provide a structured way to define and enforce validation rules	Offer flexibility without the constraints of a library
Simplified Setup	Require an integration of the library and learning its features	Quick and easy setup for simple validation requirements or small-scale projects

Considering the pros and cons outlined above, the decision to use or not use JSON schema libraries for data validation depends on factors such as the project requirements, complexity of validation rules, familiarity with JSON schemas, and the trade-off between standardization and customization in data validation processes.

Conclusion

In this article, I explore data validation various JavaScript Object Notation (JSON) Schemas libraries and show how you can use them to implement validation rules for schema validation in TypeScript. JSON Schema offers a formidable mechanism for defining and enforcing validation rules on objects, thereby ensuring data integrity and consistency.

While JSON Schema libraries provide powerful tools, sometimes custom validation tailored to specific project requirements becomes necessary. When opting for custom validation, consider the following steps:

Define Custom Validation Functions: Create custom validation functions that directly inspect the object properties and enforce your desired rules. These functions can be as simple or complex as needed.
Integrate Custom Validation Logic: Incorporate your custom validation logic into your application code. You have the flexibility to check individual properties, cross-validate fields, or apply domain-specific rules.
Error Handling and Feedback: When validation fails, provide meaningful error messages to guide users or developers. Clear feedback ensures better understanding and smoother debugging.
Unit Testing: Rigorously test your custom validation functions to ensure they behave as expected. Unit tests help catch edge cases and maintain reliability.

By embracing custom validation, you can tailor your validation rules precisely to your project’s needs.

As summarized above, both methods have their own merits. In fact, depending on your requirements, you can even apply custom validation method to validate data via JSON Schema. What are your thoughts on this matter? Feel free to leave your comments in the comment section. Much appreciated!

Validex: The Most Complete Validation Collection for React Forms

If you feel like this article helped you, please check out Validex. It has over 36 validators (such as string, password, credit card, email, file, image and more) so that you can validate React forms in minutes.

It would encourage me to continue creating even more contents. Thank you in advance! 🙏

🚀 Supercharge Your Repo for Hacktoberfest 2023

Kittisak Ma — Tue, 26 Sep 2023 12:05:00 +0000

Hi everyone! This year, I'm tasked with setting up my company's Github repositories for Hacktoberfest 2023. While researching and preparing, I thought I would share what I found to be helpful. Hope the information is useful to any maintainers out there.

Hacktoberfest, started by DigitalOcean, is celebrating its 10th anniversary this year 🥳 It is an annual event that celebrates open-source software development by having developers actively contribute to open-source projects. As of last year alone, there were over 147,000 participants.

For maintainers who want to get involved, the article will explain what Hacktoberfest is, why you should give it a try and what you need to do participate.

For maintainers who have previously participated or heard of Hacktoberfest, you can treat this as a checklist or a refresher on what you need to prepare as maintainers. It has been a year after all 😂

What is Hacktoberfest?

Hacktoberfest is an event to encourages developers to contribute to open-source projects. Contributors are encouraged to make four valid pull/merge requests to public and participating repositories to be eligible for digital rewards. It provides an opportunity for developers, both new and experienced, to engage with open-source projects and make meaningful contributions.

When and Where does it take place?

Hacktoberfest 2023 will take place between October 1 and October 31 (in any time zone, UTC-12 thru UTC+14).

Pull/merge requests is only valid if made on either via the GitHub or GitLab platform.

Why should you participate as maintainers?

Since contributors can only earn counts from qualified Pull/merge requests from issues created by maintainers, maintainers play a crucial role in the success of Hacktoberfest. By participating as a maintainer, you can benefit in various ways:

Increased community engagement: Brings attention to your project and attracts new contributors, kickstarting or fostering an active community around your repository going forward.
Quality contributions: Ensure that the contributions made to your project are meaningful and adhere to your project's guidelines and standards. More on ways to handle spam in the next section.
Skill development and collaboration: Provides a great opportunity to collaborate with developers from diverse backgrounds, learn from others, and improve your coding skills.

Note: Although maintainers who review Pull/merge requests from others do not get digital rewards, you are still eligible for rewards if you submit Pull/merge requests to other participating repositories or even your own repositories.

Wouldn't there be a lot of spam?

There is a strict rule of disqualification by Hacktoberfest

Pull/merge requests that have a label containing the word spam won’t be counted, and participants with two or more requests identified as spam will be disqualified

However, due to the nature of the event, spams are definitely possible. The benefits definitely outweigh the trouble for maintainers who are looking to get more attention. For other maintainers, participating is one of the ways to give back to the open-source community. So what better timing to foster a stronger open-source community to attract new contributors (beginner or experienced developers).

To further minimize spam, here are some more suggestions:

Contribution guidelines: Set up clear contribution guidelines to discourage spammy contributions. Include requirements such as meaningful code changes, proper documentation updates, or thorough bug reports. Here is an amazing contributing template by @nadia to get started. For a good real-life example, you may want to check out Amplication.
Communication and feedback: Engage with contributors by providing constructive feedback if you consider a contribution a spam or invalid. By being patient and offering guidance and suggestions to improve their contributions, you can create a more welcoming environment for everyone to thrive in.

How to participate as maintainers?

Step 1A: Add a `hacktoberfest` topic to your repository

Step 1B: Add `hacktoberfest-accepted` label to your issue

Note: You can also choose to do both steps.

Step 2: Create meaningful issues

Like how we don't like contributors to spam us, we should not create "spam" issues. Bad issues like adding a name or profile to a list or arbitrarily curating content should be discouraged. Anyone can report a repository for Hacktoberfest to investigate.

Although you may not need to prepare much for existing contributors of your repositories, you may want to create issues with good first issue for new contributors who still unfamiliar with your repository to get involved. In my opinion, ToolJet and Posthog have great examples of good first issue.

Besides issues related to coding, you can also create issues that are low-code or non-code in nature such as writing technical documentation, tutorials , blog posts, translating to different languages and many more. For more inspiration, please check out more examples at 8 non-code ways to contribute to open source.

Note: For more information, please see low-or-non-code section of Hacktoberfest.

Review Pull/Merge Request

It's important to be kind and patient. If Pull/merge requests are rejected due to spam or invalid contributions, please explain to them. Some contributors may just be making honest mistakes. Everyone is a beginner at first 🤭

Conclusion

Preparing your Github repository for Hacktoberfest is essential to attract contributors, foster collaboration, and maintain the overall quality of your project. By actively engaging with the Hacktoberfest community and providing support to contributors, you can create a welcoming environment for open-source contributions.

Could you support me by starring Berryjam repo?

Berryjam is a UI components analyzer for Vue 3 & Nuxt to detect component usage, relationships and more. If you feel this article is useful, could you consider starring ⭐⭐⭐ Berryjam’s Github repo?

It would mean the world and encourage me to create more content.

Thank you in advance! 🙏

P.S Feel free to add your or other repos that you wish people would contribute to in the comment section.

🎉Introducing Atomic Design in Vue.js [Updated]🔥

Kittisak Ma — Wed, 23 Aug 2023 12:10:56 +0000

In my experience of building and delivering systems for various clients, depending on their requirements or preferences, it’s inevitable that I may use UI frameworks and libraries like Ant Design and Tailwind. Often, I have to build on top of each components. If you are working alone, it’s not such a big problem. But when working as a team, things get complicated quickly. So, I started looking at different methodologies which can provide development flexibility and system maintainability for the projects I’m leading. I choose Atomic Design methodology and want to share why it works for me.

Atomic Design is a methodology for creating design systems that breaks down user interfaces into small, reusable components, namely:

Atoms
Molecules
Organisms
Templates
Pages

By following a modular approach to design, atomic design helps teams to create consistent, scalable, and maintainable UIs.

In this post, for simplicity, we'll explore how to implement Atomic Design in Vue.js with only HTML. I'll start with the basics of Atomic Design and then demonstrate how to apply its principles in Vue.js.

At the end of the article, you will get a page that consists of a header, a form and a footer. You can use the example here to apply to any UI framework.

You may notice that each component has borders around it. This is intentional so you can identify whether it's an atom, a molecule, or an organism.

Vue-PDF-Viewer: A Versatile and Powerful PDF Solution for Vue.js

Here’s a little background on what I’ve been working on—Vue PDF Viewer. This library makes it easy to render PDF documents right within your Vue or Nuxt applications, allowing users to interact with PDFs directly on your site. With features like theme customization, built-in localization, and responsive design, it’s crafted to offer a flexible and seamless user experience tailored to your project’s needs.

If you find this helpful, I’d love for you to check out Vue PDF Viewer. Your support inspires me to keep creating and improving tools for the developer community!

Anatomy of Atomic Design

Atomic Design consists of five levels that represent the building blocks of UIs. For this example, I have created an inverted tree structure to visualizing how each anatomy is connected.

- Page
 - Full Layout Template
  - Header Organism
    - Logo Atom
    - Search Form Molecule
      - TextBox Atom
      - Button Atom
  - Content Organsim
    - Form Molecule
      - 2x TextBox Atoms
      - Button Atom
  - Footer Organism
    - Copyright Atom
    - Subscribe Form Molecule
      - TextBox Atom
      - Button Atom

1. Atoms

Atoms are the smallest units of UI that cannot be broken down further without losing their meaning. Examples of atoms include icons, buttons, labels, inputs, and typography.

In Vue.js, atoms can be created as reusable components that accept props to customize their appearance and behavior. For this instance, we have a few atoms to prepare for:

Textbox

<template>
<div class="component-wrapper" data-name="textBoxAtom">
  <label>{{ label }}: <input type="text" :placeholder="placeHolder" /></label>
</div>
</template> 

<script>
export default { 
  name: 'TextBoxAtom', 
  props: { 
    label: {
      type: String,
      default: 'labelName'
    }, 
    placeHolder: String, 
  }, 
}; 
</script>
<style scoped>
  input{
      padding: 0.75em 2em;
  }
</style>

Button

<template>
 <div class="component-wrapper" data-name="buttonAtom">
  <button :disabled="disabled"> 
    <slot>Button</slot>
  </button> 
 </div>
</template> 

<script>
export default { 
  name: 'ButtonAtom', 
  props: { 
    type: String, 
    size: String, 
    disabled: Boolean,
  },  
}; 
</script>
<style scoped>
button {
  color: #4fc08d;
}
button {
  background: none;
  border: solid 1px;
  border-radius: 2em;
  font: inherit;
  padding: 0.5em 2em;
}
</style>

Logo

<template>
  <div class="component-wrapper" data-name="logoAtom">
    <img :src="computedImageUrl" alt="logo"/>
  </div>
</template>

<script>
export default {
  props: {
    width: {
      type: Number,
      default: 50
    },
    height: {
      type: Number,
      default: 50
    }
  },
  computed: {
    computedImageUrl() {
      return `https://picsum.photos/${this.width}/${this.height}`
    }
  }
};
</script>

For a closer look, you can check out the codes in the Atoms collection.

2. Molecules

Molecules are combinations of two or more atoms that work together to perform a specific function. In Vue.js, molecules can be created by composing atoms as child components within a parent component. Examples of molecules include forms, search bars, navigation menus, and cards.

Referring to the example above, we will need to combine the atoms to create the following molecules:

Subscribe Form Molecule

<template>
  <form class="component-wrapper" data-name="subscribeFormMolecules">
    <TextboxAtom label="Email" />
    &nbsp;
    <ButtonAtom>Subscribe</ButtonAtom>
  </form>
</template>

<script>
import TextboxAtom from "https://codepen.io/9haroon/pen/LYXgdKg.js";
import ButtonAtom from "https://codepen.io/9haroon/pen/BaGqrJg.js";
export default {
  components: { ButtonAtom, TextboxAtom }
};
</script>
<style scoped>
form {
  display: inline-flex;
}
</style>

Search Form Molecule

<template>
  <form class="component-wrapper" data-name="searchFormMolecules">
    <InputAtom label="Search" />
    <ButtonAtom>Search</ButtonAtom>
  </form>
</template>

<script>
import InputAtom from "https://codepen.io/9haroon/pen/LYXgdKg.js";
import ButtonAtom from "https://codepen.io/9haroon/pen/BaGqrJg.js";
export default {
  components: { ButtonAtom, InputAtom }
};
</script>
<style scoped>
form {
  display: inline-flex;
}
</style>

Form Molecule

<template>
  <div class="form-molecule component-wrapper" data-name="formMolecules">
    <div><InputAtom :label="nameLabel" :placeholder="namePlaceholder" /></div>
    <div><InputAtom :label="emailLabel" :placeholder="emailPlaceholder" /></div>
    <p>
      <ButtonAtom :disabled="isSubmitDisabled">
        {{ submitLabel || "Button" }}
      </ButtonAtom>
    </p>
  </div>
</template>

<script>
import InputAtom from "https://codepen.io/9haroon/pen/LYXgdKg.js";
import ButtonAtom from "https://codepen.io/9haroon/pen/BaGqrJg.js";
export default {
  name: "FormMolecule",
  components: {
    InputAtom,
    ButtonAtom
  },
  props: {
    nameLabel: String,
    namePlaceholder: String,
    emailLabel: String,
    emailPlaceholder: String,
    submitLabel: String,
    isSubmitDisabled: Boolean
  }
};
</script>

You can find the codes in the Molecules collection.

3. Organisms

Organisms are combinations of molecules that form distinct sections of a UI, such as headers, footers, sidebars, and content blocks. In Vue.js, organisms can be created by composing molecules as child components within a layout component.

For this exercise, three organisms are needed.

Header Organism

<template>
  <header class="component-wrapper" data-name="headerOrganism">
    <LogoAtom width="60" />
    <SearchFormMoecules />
  </header>
</template>

<script>
import SearchFormMoecules from "https://codepen.io/9haroon/pen/zYMmjqa.js";
import LogoAtom from "https://codepen.io/9haroon/pen/xxQMbeJ.js";
export default {
  components: { SearchFormMoecules, LogoAtom }
};
</script>
<style scoped>
header {
  min-height: 50px;
  display: flex;
  justify-content: space-between;
  align-items: center;
}
</style>

Content Organism

<template>
  <div class="page-organism">
    <div class="content-wrapper-title">
      <h1><slot name="title">Here might be a page title</slot></h1>
      <p><slot name="description">Here might be a page description</slot></p>
    </div>
    <slot>...</slot>
    <!--   This might includes some molecules or atoms   -->
  </div>
</template>
<script>
export default {
  name: "ContentOrganism",
  components: {}
};
</script>
<style scoped>
.page-organism {
  padding-top: 50px;
  padding-bottom: 80px;
  box-shadow: inset 0px 10px 15px -3px rgba(0, 0, 0, 0.1);
}
.content-wrapper-title {
  text-align: center;
}
</style>

Footer Organism

<template>
  <footer class="component-wrapper" data-name="footerOrganism">
    <CopyrightAtom />
    <SubscribeFormMoecules />
  </footer>
</template>

<script>
import SubscribeFormMoecules from "https://codepen.io/9haroon/pen/ExOrarL.js";
import LogoAtom from "https://codepen.io/9haroon/pen/xxQMbeJ.js";
import CopyrightAtom from "https://codepen.io/9haroon/pen/gOQqOBj.js";
export default {
  components: { SubscribeFormMoecules, LogoAtom, CopyrightAtom }
};
</script>
<style scoped>
footer {
  display: flex;
  justify-content: space-between;
  align-items: center;
}
</style>

Per usual, here's a collection of organisms' codes that I've created.

4. Templates

Templates are the structures that define the layout and composition of pages by specifying the placement and size of organisms within regions, such as headers, footers, and content areas.

In Vue.js, templates can be created as parent components that accept named slots for child components. Applying the 3 organisms to the Templates concept, here is how it could look like.

<template>
  <div class="full-layout-template">
    <HeaderOrganism />
    <ContentOrganism class="content">
      <template #title>
        <slot name="title">default title</slot>
      </template>
      <template #description>
        <slot name="description">default description</slot>
      </template>
      <slot />
    </ContentOrganism>
    <FooterOrganism class="page-footer" />
  </div>
</template>
<script>
import HeaderOrganism from "https://codepen.io/9haroon/pen/WNYaJGR.js";
import ContentOrganism from "https://codepen.io/9haroon/pen/vYQbOeO.js";
import FooterOrganism from "https://codepen.io/9haroon/pen/RwqvPRN.js";
export default {
  name: "FullLayoutTemplate",
  components: {
    HeaderOrganism,
    ContentOrganism,
    FooterOrganism
  }
};
</script>
<style scoped>
.full-layout-template {
  display: flex;
  flex-direction: column;
  min-height: 90vh;
}
.content {
  flex: 1 0 auto;
}
.page-footer {
  flex-shrink: 0;
}
</style>

here is the CodePen's link of the template

5. Pages

Pages are the final presentation of UIs that combine templates with specific content to form complete views. In Atomic Design, pages are like instances of templates that represent unique experiences for users.

In Vue.js, pages can be created by copying a template and replacing its slots with actual content. Although, in this example, I only change the content of Content Organism, you could choose to change all or no content.

<template>
  <FullLayoutTemplate>
    <template #title>{{ title }}</template>
    <template #description>{{ description }}</template>
    <div class="fixed-width">
      <FormMolecule nameLabel="Name" emailLabel="Email" submitLabel="Save" />
    </div>
  </FullLayoutTemplate>
</template>
<script>
import FullLayoutTemplate from "https://codepen.io/9haroon/pen/GRwzpxx.js";
import FormMolecule from "https://codepen.io/9haroon/pen/PoxyRMo.js";
export default {
  name: "HomePage",
  components: {
    FullLayoutTemplate,
    FormMolecule
  },
  data() {
    return {
      title: "Welcome to my example",
      description: "This is an example of Atomic Design in Vue.js",
      copyright: "Copyright © 2023"
    };
  }
};
</script>
<style scoped>
* {
  font-family: Avenir, Helvetica, Arial, sans-serif;
}
.fixed-width {
  max-width: 350px;
  margin: 0 auto;
}
</style>

here is the CodePen's link of the page

🆕 Update: While this article uses Vue 2 in its code examples, I've also created a full Vue 3 + Composition API + TypeScript version on Stackblitz.

👉 Try it on Stackblitz

Benefits of Atomic Design in Vue.js

By using Atomic Design in Vue.js, you can achieve several benefits, such as:

Consistency: By creating reusable components, you ensure that your UIs look and behave consistently across all pages.
Scalability: By breaking down UIs into small pieces, you can easily add, remove, or update components without affecting other parts of the system.
Maintainability: By organizing components into folders and files, you can easily find, edit, or debug them in isolation from other parts of the system.
Reusability: By creating standalone components, you can reuse them in other projects or share them with the community, thus saving time and effort.

Atomic Design is a powerful methodology that can help you design better UIs in Vue.js. By following its principles, you can create reusable, modular, and scalable components that make your code more maintainable and your users more satisfied. So, go ahead, give it a try, and let me know how it worked for you!

Vue PDF Viewer: A Complete PDF Solution for Vue.js

If you’re looking for a powerful, flexible solution for rendering PDFs directly in your Vue or Nuxt applications, Vue PDF Viewer is the tool for you. Offering a wide array of features—like theme customization, localization support, and responsive layouts—it’s built to handle a range of project requirements while delivering a seamless, user-friendly experience.

If this sounds useful to you, feel free to explore Vue PDF Viewer and see how it can enhance your next project. It would mean the world and encourage me to create more content.

Thank you in advance! 🙏

DEV Community: Kittisak Ma

PDFium vs PDF.js: Choosing a React PDF Engine (2026)

What PDFium and PDF.js actually are

The library landscape: which engine is under your viewer

Rendering fidelity: fonts, color, and complex graphics

Color and CMYK

Turning it on, and the trap

Fonts and CJK

The gap is a moving target

Rendering performance on heavy and complex PDFs

Forms and form fidelity

Where PDF.js pulls ahead: bundle size, text, and accessibility

Bundle size and load model

Text, search, and accessibility

A smaller security surface

What this means in a React project

PDFium vs PDF.js: how to choose

How to Add PDF Annotations in Vue.js: PDF.js, vue-pdf-embed, @tato30/vue-pdf, and Vue PDF Viewer (2026)

Rendering, creating, and persisting are three different jobs

Rendering existing PDF annotations costs you one prop

Creating PDF annotations is where the libraries come apart

The PDF.js annotation editor

@tato30/vue-pdf's editor-layer is that same editor in Vue clothing

pdf-lib, for when you just need it burned in

The Vue PDF Viewer annotation plugin

Persisting PDF annotations is the part that bites you later

When you actually need the enterprise tier

Picking a path

What to decide before you install anything

How to Build a React PDF Viewer for Next.js in Minutes

Why React PDF?

Step 1: Set up a Next.js Project

1.1 Visit StackBlitz & Create a New Project

1.2 Wait for StackBlitz to Set Things Up

Step 2: Integrate React PDF into a Next.js Project

2.1 Install React PDF

2.2 Set Up the Viewer

Add RPConfig at the Root Level

Step 3: Create a Reusable PDF Viewer Component

Build the AppPdfViewer component

Create a Lazy-Loaded Wrapper Component

Use the PDF Viewer in Your App

Looking for a Faster Setup?

Common Use Cases

Customize the PDF Viewer to Match Your Branding

Customize Any Toolbar Icon

Conclusion

🔥 Understanding PDF.js Layers and How to Use them in React.js

React PDF: Flexible and Powerful React PDF Viewer

Overview of PDF.js Layers

Step 1: Set up React.js Project

Step 2: Integrate PDF.js into a React project

1. Canvas Layer

Purpose

How It Works

Use Cases

Example of Canvas Layer Code with React

📜 How the Code Works

(1) Fetching and Loading the PDF

(2) Rendering the Canvas Layer

2. Text Layer

Purpose

How It Works

Use Cases

Text layer Code Example

📜 How the Code Works

(1) Fetching and Loading the PDF

(2) Structuring the Layers

(3) Rendering the Text Layer

3. Annotation Layer

Purpose

How It Works

Use Cases

Annotation layer Code Example

📜 How the Code Works

(1) Fetching and Loading the PDF

(2) Structuring the Layers

(3) Rendering the Annotation Layer

(4) Handling Internal Link Clicks

(5) Handling Page Navigation

Build the `AppPdfViewer` component