Build your own PDF viewer

The headless packages give you everything a PDF viewer does, without a look of their own: pages that scroll and zoom, crisp rendering, text selection and search, annotations, forms and signatures. You build the interface in React, and nothing appears on screen unless you put it there.

import { Viewer, DocumentGate } from '@embedpdf/react/runtime';
import { Stage, stagePlugin } from '@embedpdf/react/stage';
import { RenderLayer, renderPlugin } from '@embedpdf/react/render';
import { cloudEngine } from '@cloudpdf/engine';
import { fetchDocumentToken } from './api';

const engine = cloudEngine({ baseUrl: 'https://pdf.example.com' });
const plugins = [stagePlugin(), renderPlugin()];

export function App() {
  return (
    <Viewer
      engine={engine}
      plugins={plugins}
      initialDocuments={[{ source: { kind: 'token', token: () => fetchDocumentToken('contract') } }]}
    >
      <DocumentGate fallback={<p>Opening…</p>}>
        <Stage style={{ height: 600 }}>{() => <RenderLayer />}</Stage>
      </DocumentGate>
    </Viewer>
  );
}

That’s a complete viewer: the pages scroll, zoom with a pinch or Ctrl and the wheel, and stay sharp at every zoom. Everything else is a plugin you add, and a few lines of your own UI.

Headless or the ready-made Viewer?#

EmbedPDF comes in two forms, built on the same engine and plugins:

• The Viewer is finished: a toolbar, sidebars, annotation tools and search, ready in minutes. You configure it and theme it.
• Headless is the parts: you decide what the toolbar looks like, where the search box goes, and what happens when someone clicks an annotation.

Choose headless when the viewer is part of your product’s own interface. You can start with the Viewer and move to headless later: the plugins and their options are the same.

How it’s put together#

A headless viewer has five parts. You meet them on every page:

• The engine opens and reads PDF files. It runs in the browser, or on your server with CloudPDF.
• <Viewer> starts the engine, opens documents, and holds the plugins.
• Plugins add one feature each: search, annotations, forms. Register the ones you need; the rest never reach your bundle.
• Layers draw inside each page: the page itself, the text selection, the annotations.
• Hooks connect your own UI: useSearch() to search, useSearchState() to show the results, useSearchEvent() to react when something happens.

How it works explains each in a few minutes.

Every plugin#

Each plugin is one import line. Registering a plugin and importing its components come from the same place:

Local or cloud#

The same viewer runs on either engine. Only how you create the engine and open a document differs; every plugin, hook and component stays the same.

The CloudPDF engine keeps the file on your server. Pages arrive as images, so the first page shows at once; every call is checked against the user’s token; and annotations and form values are stored as people make them, with everyone who has the document open seeing each other’s changes.

Next steps#