Setup

One package gives you the whole viewer: the toolbar and panels, and the engine that opens your documents on CloudPDF.

npm install @cloudpdf/viewer-react@next

On a plain HTML page, load the script from jsDelivr as above. In an app with a bundler, install @cloudpdf/viewer and import '@cloudpdf/viewer' once, which defines the <embedpdf-viewer> element.

Give it a size#

The viewer fills the box you give it and scrolls the pages inside it, so the box needs a height. Any height works: a fixed one, 100vh, or the remaining space of a flex or grid layout (flex: 1; min-height: 0). Its width follows the box too, and the viewer adapts to it, not to the window: see Small screens.

Pass it config#

Everything the viewer can do is one config object. In a framework, every key is a prop:

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

export function Report() {
  return (
    <PDFViewer
      src={{ shareToken: 'shr_WGj1goAtlNN_fQ5OswPrbJQM' }}
      theme="system"
      disable={['forms']}
      onReady={(viewer) => console.log('ready', viewer)}
      style={{ height: '100vh' }}
    />
  );
}

Who the user is and what they may do come from the document’s token, so there’s no scope or identity.

The config is plain data and a few functions, the same in every framework. Keep it in a file of its own when it grows, and spread it into the viewer, as in the Quick start.

TypeScript#

Every key is typed, including the ids of the built-in buttons and panels, so your editor completes them. A config in a file of its own gets its types from satisfies:

import type { ViewerConfig } from '@cloudpdf/viewer';
 
export const config = {
  theme: { accent: '#7c3aed' },
  layout: (layout) => layout.place('main', 'bottom'),
} satisfies ViewerConfig;

Every framework package exports the same ViewerConfig type.

Server-side rendering#

The viewer runs in the browser only, and every framework package is safe to import on the server. The server renders an empty box of the size you gave it, and the viewer starts when the page loads in the browser, so there’s nothing to wrap:

// app/report/page.tsx: a server component. <PDFViewer> is a client component already.
import { PDFViewer } from '@cloudpdf/viewer-react';

export default function ReportPage() {
  return <PDFViewer src={{ shareToken: 'shr_WGj1goAtlNN_fQ5OswPrbJQM' }} style={{ height: '100vh' }} />;
}

Next.js, Nuxt, SvelteKit, Astro and Angular SSR all work this way. With Angular, @defer (on viewport) also keeps the viewer’s code out of the first download until it scrolls into view.

Open a CloudPDF document#

Each document opens with a token your backend creates for the user. It says who they are and what they may do:

{
  src: { token: await fetchDocumentToken('contract-42') },
}

Pass a function to get a fresh token when an old one runs out: src: { token: () => fetchDocumentToken('contract-42') }. See Authentication for the ways to open a document and what a token carries.

Change the config later#

Five keys follow their prop while the viewer runs: src opens the new document in place of the old one; theme and locale switch the look and the language; disable and readOnly take tools away or bring them back. Any plugin’s settings change through the viewer (see The viewer in code). Everything else is read once, when the viewer starts. To change it, mount a new viewer:

import { PDFViewer, type Layout } from '@cloudpdf/viewer-react';

const toolbarAtBottom = (layout: Layout) => layout.place('main', 'bottom');

export function Report({ toolbarBelow }: { toolbarBelow: boolean }) {
  // A new key mounts a new viewer with the new config.
  return (
    <PDFViewer
      key={toolbarBelow ? 'below' : 'above'}
      src={{ shareToken: 'shr_WGj1goAtlNN_fQ5OswPrbJQM' }}
      layout={toolbarBelow ? toolbarAtBottom : undefined}
      style={{ height: '100vh' }}
    />
  );
}

A new viewer opens its documents again.

Several viewers on a page#

Each viewer has its own documents, layout, settings and state. Keyboard shortcuts work in the viewer that has focus, so two viewers never both zoom on one key press.

Good to know#

What it needs from the browser#

Chrome and Edge 114, Firefox 125 and Safari 17 (iOS 17), or newer: the first versions with the popover API, which the viewer’s menus and dialogs open in.

The pages render on CloudPDF. Stamps and Signatures open their libraries in the browser, in a Web Worker, as WebAssembly.

A strict Content Security Policy#

The viewer runs under a strict CSP with no 'unsafe-inline'. Security & CSP has the policy to copy.

Air-gapped and self-hosted#

The viewer talks to one server: CloudPDF SaaS, or your own CloudPDF when engine: { baseUrl } names it. See Self-hosting for running your own and the files the browser loads.