DEV Community: korial29

A PDF Viewer Web Component That Doesn't Make You Choose Between Themeable and Lightweight

korial29 — Wed, 29 Jul 2026 13:48:44 +0000

Drop a PDF into a web page and you usually end up picking one of two uncomfortable options: embed PDF.js's own viewer in an <iframe> (works, but you're stuck behind an iframe boundary — no theming, no styling it to match your app), or pull in pdfjs-dist directly and build your own toolbar, zoom controls, search, and page navigation from PDF.js's fairly low-level rendering API.

lit-pdf-viewer is a native web component that skips both compromises: a real custom element (not an iframe), with a full toolbar already built, that you can theme like any other element on your page.

Why a custom element, specifically

<lit-pdf-viewer> is a Web Component — no React/Vue/Angular adapter needed. Because custom elements are a browser primitive rather than a framework integration, it behaves identically everywhere:

<script type="module">
  import 'lit-pdf-viewer';
</script>

<lit-pdf-viewer src="path/to/document.pdf"></lit-pdf-viewer>

Or inside a Lit component, same element, same API:

import 'lit-pdf-viewer';
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';

@customElement('my-app')
class MyApp extends LitElement {
  render() {
    return html`<lit-pdf-viewer src="path/to/document.pdf"></lit-pdf-viewer>`;
  }
}

It fills the height of its host, so give it one:

lit-pdf-viewer {
  display: block;
  height: 100vh;
}

The bundle cost, honestly

Adding the component costs about 17 KB gzipped — that's the whole thing, Lit runtime included, before you've loaded a single PDF. PDF.js itself (~196 KB gzipped) is only pulled in via a dynamic import() once a <lit-pdf-viewer> actually connects to the page or a print is triggered — not just for having the package listed in your dependencies.

What's in the toolbar

Not a bare canvas — the toolbar, search, and page controls ship built in:

Zoom: page-fit, page-width, actual size, or a custom numeric level
Page navigation: previous/next, first/last, direct page input
Text search, including multi-phrase search and a whole-word mode
Rotate clockwise / counter-clockwise
Text selection and hand-tool modes, full-screen, download, print (with an optional separate higher-quality print source)
Keyboard accessibility

const terms = ['invoice total', 'due date'];

html`
  <lit-pdf-viewer src="invoice.pdf" .searchQueries=${terms}></lit-pdf-viewer>
`;

<!-- Serve a screen-optimized PDF but print a higher-quality one -->
<lit-pdf-viewer src="document-screen.pdf" printSrc="document-print.pdf"></lit-pdf-viewer>

Theming through the shadow boundary

Every visual surface — toolbar background, buttons, icons, the search bar, tooltips, the error banner — is driven by CSS custom properties with sensible defaults. Set them on the element itself, or any ancestor (:root included), and they inherit down through every nested shadow root automatically — no ::part() gymnastics required for the common case:

lit-pdf-viewer {
  --litpdf-toolbar-background: #1e1e1e;
  --litpdf-icon-color: #eee;
  --litpdf-accent-color: #ff6b35;
  --litpdf-surface-background: #2a2a2a;
  --litpdf-text-color: #eee;
}

i18n out of the box

Toolbar, search bar, error panel, and loading indicator are translated in English, French, Spanish, and German, auto-detected from navigator.language with English as the fallback:

<lit-pdf-viewer src="doc.pdf" locale="es"></lit-pdf-viewer>

Override individual strings (or add a language of your own) without losing the rest of the resolved locale:

html`
  <lit-pdf-viewer
    src="doc.pdf"
    locale="en"
    .translations=${{
      toolbar: { print: 'Print document' },
      search: { placeholder: 'Find in this document...' },
    }}
  ></lit-pdf-viewer>
`;

Where this sits relative to the alternatives

A few other PDF-in-the-browser web components already exist, and they're worth knowing about: pdfjs-viewer-element wraps PDF.js's own default viewer inside an isolated <iframe> — a solid drop-in choice if you don't need it to look like the rest of your app. pdf-viewer-element (from Lit's own creator) stays intentionally close to the metal — a rendering primitive rather than a full toolbar. lit-pdf-viewer targets the space between the two: a real, styleable custom element with the toolbar, search, and i18n already built, for the common case of "I want a PDF viewer in my page that looks like it belongs there."

Install

npm install lit-pdf-viewer
npx lit-pdf-viewer-install <your-public-dir>

The second command copies the PDF.js worker, CMaps, and icon font into your public directory — required static assets the component serves alongside your app.

npm: lit-pdf-viewer
source: github.com/korial29/lit-pdf-viewer
live demo: korial29.github.io/lit-pdf-viewer

Apache-2.0 licensed. Issues and PRs welcome.

Building Form-Associated Custom Elements with ElementInternals

korial29 — Wed, 29 Jul 2026 13:33:33 +0000

Web components have been able to fully participate in native HTML forms since 2023 — submit their value with FormData, trigger :invalid, reset alongside the <form>, the works. The API that makes it possible, ElementInternals, is now supported in Chromium, Firefox, and Safari 16+.

The catch: nobody tells you it's about 40 lines of repetitive plumbing per component. This post walks through what that plumbing looks like, then shows a small reusable mixin (form-control-mixin) that gets rid of it.

What "form-associated" actually buys you

A form-associated custom element can:

submit a value as part of the form's FormData, under its name attribute
expose validity through the same ValidityState interface native inputs use (valueMissing, tooShort, patternMismatch, …)
react to the form being reset, its ancestor <fieldset> being disabled, or the browser restoring state (bfcache, autofill)

All of that lives behind HTMLElement.attachInternals(). Here's the minimum viable version, no library, no framework:

class RequiredInput extends HTMLElement {
  static formAssociated = true;

  #internals = this.attachInternals();

  connectedCallback() {
    this.innerHTML = '<input>';
    this.querySelector('input').addEventListener('input', (e) => {
      this.#internals.setFormValue(e.target.value);
      this.#internals.setValidity(
        e.target.value ? {} : { valueMissing: true },
        'Please fill out this field.',
      );
    });
  }

  formResetCallback() {
    this.querySelector('input').value = '';
  }
}

customElements.define('required-input', RequiredInput);

That's one validator, on one field, with no reset-syncing of validity, no disabled handling, no styling hook for "the user actually touched this field." Add a second validator, or a second component, and you're rewriting the same setFormValue/setValidity dance every time.

The reusable version

form-control-mixin wraps that plumbing in a mixin you apply to any class extending HTMLElement — a plain custom element, a LitElement, a Stencil or FAST base class:

npm install form-control-mixin

import { FormControlMixin, requiredValidator, minLengthValidator } from 'form-control-mixin';

class MyInput extends FormControlMixin(HTMLElement, {
  validators: [requiredValidator, minLengthValidator(3)],
}) {
  value = '';

  connectedCallback() {
    this.requestValidation();
  }

  formResetCallback() {
    this.value = '';
    this.requestValidation();
  }
}

customElements.define('my-input', MyInput);

<form>
  <my-input name="nickname"></my-input>
  <button>Submit</button>
</form>

new FormData(form).get('nickname'), :invalid, reportValidity(), the browser's native validation bubble — all of it works, because the mixin is just calling the same ElementInternals methods you'd call by hand, in the right order, every time requestValidation() runs.

Validators are plain objects — { key, message, isValid(host, value) } — checked in order, first failure wins. Nine ship built in: requiredValidator, minLengthValidator, maxLengthValidator, patternValidator, emailValidator, urlValidator, minValidator, maxValidator, stepValidator, mirroring the native required/minlength/maxlength/pattern/type="email"/type="url"/min/max/step semantics respectively. Writing your own — an async username-availability check, a cross-field comparison — is the same three-property shape.

Styling interaction state without attribute soup

This is the part that usually gets bolted on later as a pile of reflect: true properties and manual classList.toggle() calls. ElementInternals has a states property — a CustomStateSet — built exactly for this, and the mixin keeps it in sync automatically:

my-input:state(invalid) {
  outline: 2px solid crimson;
}

/* only complain once the user has actually left the field */
my-input:state(touched):state(invalid) {
  background: #fdeced;
}

my-input:state(dirty) {
  border-color: #6355ff;
}

valid/invalid mirror validity.valid. touched flips on the first focusout. dirty flips once the value diverges from whatever it was on the first requestValidation() call. No attributes, no re-renders triggered by styling concerns — just CSS reacting to state the component already has to track anyway.

Why cross-browser testing isn't optional here

If you reach for jsdom to test any of this — don't. jsdom doesn't correctly implement ElementInternals: form association, setFormValue, and the validity plumbing either no-op or throw depending on the version. Tests will pass while the actual behavior is broken in a real browser, which is worse than having no tests at all.

form-control-mixin's own suite runs against real Chromium, Firefox, and WebKit via @web/test-runner + Playwright — the same engines your users actually run.

Why this exists

An attempt at solving this generically already exists — @open-wc/form-control — but it hasn't had a release in about three years and never settled on a finished API. Bigger component libraries (Shoelace, Ionic, FAST) solved the same problem, but only inside their own codebase, not as something you can install if you're building your own design system from scratch.

form-control-mixin is ~3 KB gzipped, has zero runtime dependencies, ships its own TypeScript types, and doesn't assume Lit or any other renderer.

npm: form-control-mixin
source: github.com/korial29/form-control-mixin
live demo: korial29.github.io/form-control-mixin/demo

MIT licensed. Issues, PRs, and "here's a validator I wish existed" requests are all welcome.