📚 Documentation

The full walkthrough, advanced examples, and API reference live in our docs site:

👉 https://www.embedpdf.com/react-pdf-viewer

🚀 Introduction

The @embedpdf/react-pdf-viewer package provides a complete, production-ready PDF viewing experience for React applications.

It is designed to be the fastest way to get a high-quality PDF viewer into your app. You don't need to build toolbars, handle layout logic, or worry about CSS—it just works.

Key Features

• Ready-to-use UI — Includes a polished toolbar, sidebar, and thumbnails.
• Responsive — Adapts seamlessly to mobile and desktop screens.
• Themable — Built-in light/dark modes and support for custom brand colors.
• Configurable — Easily disable features you don't need (e.g., printing or downloading).
• TypeScript — Fully typed for a great developer experience.
• Next.js Ready — Works flawlessly with Next.js App Router and SSR.

📦 Installation

npm install @embedpdf/react-pdf-viewer
# or
pnpm add @embedpdf/react-pdf-viewer
# or
yarn add @embedpdf/react-pdf-viewer

🛠 Basic Usage

Import the PDFViewer component and render it with a PDF source.

import { PDFViewer } from '@embedpdf/react-pdf-viewer';

export default function App() {
  return (
    <div style={{ height: '100vh' }}>
      <PDFViewer
        config={{
          src: 'https://snippet.embedpdf.com/ebook.pdf',
          theme: { preference: 'light' },
        }}
      />
    </div>
  );
}

That's it! You now have a fully functional PDF viewer.

Next.js App Router

The component works seamlessly with Next.js. Since it uses browser APIs (Canvas, WebAssembly), make sure to use it in a Client Component:

'use client';

import { PDFViewer } from '@embedpdf/react-pdf-viewer';

export default function ViewerPage() {
  return (
    <div style={{ height: '100vh' }}>
      <PDFViewer
        config={{
          src: 'https://snippet.embedpdf.com/ebook.pdf',
        }}
      />
    </div>
  );
}

🎨 Customization

Theme

The viewer includes a robust theming system. You can set the preference to 'light', 'dark', or 'system', and even override specific colors to match your brand.

<PDFViewer
  config={{
    src: '/document.pdf',
    theme: {
      preference: 'system',
      light: {
        accent: {
          primary: '#9333ea', // Custom brand color (Purple)
        },
      },
    },
  }}
/>

Disabling Features

Easily customize the UI by disabling features you don't need via the disabledCategories option:

<PDFViewer
  config={{
    src: '/document.pdf',
    disabledCategories: ['annotation', 'print', 'export'],
  }}
/>

Available categories include: zoom, annotation, redaction, document, page, panel, tools, selection, and history.

⚙️ Configuration Options

The config prop accepts the following top-level options:

| Option | Type | Description | | :------------------- | :---------------------------------- | :--------------------------------------------- | | src | string | URL or path to the PDF document. | | theme | object | Theme configuration (preference, overrides). | | tabBar | 'always' \| 'multiple' \| 'never' | Control visibility of the document tab bar. | | disabledCategories | string[] | Hide specific UI features by category. | | i18n | object | Configure locales and translations. | | annotations | object | Configure annotation defaults (author, tools). | | zoom | object | Configure default zoom levels and limits. | | scroll | object | Configure scroll direction and logic. |

🔌 Accessing the Engine & Registry

For advanced use cases, you can access the underlying PDFium engine or the plugin registry using a ref.

import { useRef } from 'react';
import { PDFViewer, PDFViewerRef } from '@embedpdf/react-pdf-viewer';

function App() {
  const viewerRef = useRef<PDFViewerRef>(null);

  const getMetadata = async () => {
    // Access the plugin registry
    const registry = await viewerRef.current?.registry;
    if (!registry) return;

    // Access the engine directly
    const engine = registry.getEngine();
    console.log('Engine ready:', engine);
  };

  return (
    <>
      <button onClick={getMetadata}>Get Metadata</button>
      <PDFViewer ref={viewerRef} config={{ src: '/doc.pdf' }} />
    </>
  );
}

🧩 Headless Mode

Need complete control over the UI? Building a custom design system?

Check out our Headless Components which provide hooks and logic without the UI:

npm install @embedpdf/core @embedpdf/plugin-zoom ...

Read the Headless Documentation for more details.

📄 License

EmbedPDF is MIT licensed. Commercial use is welcome—just keep the copyright headers intact.