Package Exports

react-pdf-viewer-lite

Readme

📑 react-pdf-viewer-lite

A tiny, ergonomic UI wrapper over react-pdf focused on simplicity, performance, and customization.
Drop it in, point at a PDF URL, and get a polished viewer with loader, zoom, and a pluggable control bar.

🔖 Features

Simple – one <PDFViewer /> component, sensible defaults.
Performant – minimal state, avoids reflows, no heavy runtime dependencies.
Customizable – slot-based API via render-slot for control bar & loader.
Typed – first-class TypeScript support.
Composable – bring your own toolbar or reuse the default one.

Install

npm install react-pdf-viewer-lite
---

## Quick start

```tsx
import React from 'react';
import { PDFViewer } from 'react-pdf-viewer-lite';

export default function App() {
  return (
    <div style={{ height: '100vh' }}>
      <PDFViewer initialSourceUrl="/sample.pdf" />
    </div>
  );
}

That’s it — you’ll get a loader, zoom controls, and scrolling pages out of the box.

❓ Why this component?

When the default is enough

For most apps, the built-in browser PDF viewer is perfectly fine—it’s fast, proven, and requires zero code.

When you need more

Use react-pdf-viewer-lite if you want to:

Own the controls – design your own toolbar, buttons, and UX (not whatever the browser ships).
Keep the PDF in the React tree – the document lives in the DOM, so you can style, animate, measure, and coordinate it with the rest of your UI.
Hook into behavior – listen to scrolling, loading, and zoom state; persist position; sync with app state.
Consistent cross-browser UI – same controls everywhere, no vendor chrome.

🧩 API

import type { ComponentProps, HTMLAttributes, PropsWithChildren } from 'react';
import type { Renderable } from 'render-slot';
import { Document } from 'react-pdf';

type ControlBarContext = { container: HTMLDivElement; hasLoaded: boolean };

type Props = {
  /** Initial page scale in percent (default: 100) */
  initialPageScale?: number;

  /** Initial vertical scroll offset in px (default: 0) */
  initialScrollTop?: number;

  /** Source URL of the PDF to display */
  initialSourceUrl?: string;

  /** Called on document scroll with current scrollTop */
  onDocumentScroll?: (scrollTop: number) => void;

  /** Replace/augment the control bar */
  renderControlBar?: Renderable<PropsWithChildren<HTMLAttributes<HTMLDivElement>>, ControlBarContext>;

  /** Replace/augment loader spinner (default: true) */
  renderLoaderSpin?: Renderable<HTMLAttributes<HTMLSpanElement>>;

  /** Replace/augment loader text (default: true) */
  renderLoaderText?: Renderable<HTMLAttributes<HTMLSpanElement>>;
};

🚀 Basic usage

<PDFViewer initialSourceUrl="/docs/guide.pdf" />

Custom control bar (slot)

<PDFViewer
  initialSourceUrl="/docs/guide.pdf"
  renderControlBar={(Default, { context }) => (
    <Default className="my-toolbar">
      <button onClick={() => context.container.requestFullscreen()}>
        Fullscreen
      </button>
      {!context.hasLoaded && <span>Loading…</span>}
    </Default>
  )}
/>

🎨 Styling

Override classes as needed:

.pdf-viewer__viewer
.pdf-viewer__main-frame
.pdf-viewer__content
.pdf-viewer__document-wrapper
.pdf-viewer__control-bar
.pdf-viewer__document
.pdf-viewer__loader
.pdf-viewer__loader__text
.pdf-viewer__loader__spin
.pdf-viewer__page-list-item
.pdf-viewer__zoom
.pdf-viewer__zoom__text
.pdf-viewer__zoom__icon-btn

Or replace the loader/control bar entirely via slots.

⏱️ Events

onDocumentScroll(scrollTop: number) — fires as the user scrolls the document area. Useful for restoring position.

🧪 Example (restore scroll + custom zoom)

function PersistedPDF() {
  const [scroll, setScroll] = React.useState(
    () => Number(localStorage.getItem('pdfScroll')) || 0
  );

  return (
    <PDFViewer
      initialSourceUrl="/sample.pdf"
      initialScrollTop={scroll}
      onDocumentScroll={(s) => localStorage.setItem('pdfScroll', String(s))}
      renderControlBar={(Default, { context }) => (
        <Default className="bar">
          <button
            onClick={() =>
              context.container.scrollTo({ top: 0, behavior: 'smooth' })
            }
          >
            Top
          </button>
          {!context.hasLoaded && <span>Loading…</span>}
        </Default>
      )}
    />
  );
}

💡 FAQ

Does it support large PDFs?
Yes—loading is progressive via react-pdf. The UI avoids expensive updates while bytes stream.

Can I control zoom programmatically?
The default zoom UI is included. For custom zoom, supply your own control bar and call into the context (e.g., request fullscreen, manage scale through your own controls, see PDFViewerZoom/PDFViewerControlBar in the source for patterns).

SSR?
react-pdf requires browser APIs; render this component client-side.

🗺️ Roadmap

Integrate with react-pdf 10
More events to handle
More slots to customize

Contributing

Issues and PRs welcome! Please include a minimal repro and note your environment (react, TS version).

JSPM