Moving from 2.x

3.0’s viewer replaces the one in EmbedPDF 2.x: @embedpdf/snippet, and the @embedpdf/react-pdf-viewer, @embedpdf/vue-pdf-viewer and @embedpdf/svelte-pdf-viewer packages. It’s still one tag and one config, but most names changed. Every config key is a prop, the toolbar is a layout you change in the config, and you reach each plugin by its name. This page maps each 2.x name to its 3.0 one.

The packages#

Remove the 2.x package, and install the new one:

<script type="module" src="https://cdn.jsdelivr.net/npm/@embedpdf/viewer@3/dist/embedpdf.js"></script>

The new package brings the PDF engine and its WebAssembly. If you installed @embedpdf/engines, @embedpdf/pdfium or @embedpdf/models only for the 2.x viewer, remove them too.

The viewer#

The 2.x code is the comment at the top. The 3.0 code below it does the same:

<!-- 2.x:

<div id="pdf-viewer" style="height: 100vh"></div>

<script type="module">
  import EmbedPDF from 'https://cdn.jsdelivr.net/npm/@embedpdf/snippet@2/dist/embedpdf.js';

  const container = EmbedPDF.init({
    type: 'container',
    target: document.getElementById('pdf-viewer'),
    src: '/report.pdf',
    theme: { preference: 'dark' },
    disabledCategories: ['redaction', 'document-print'],
  });
  container.registry.then((registry) => console.log('ready', registry));
</script>
-->

<div id="viewer" style="height: 100vh"></div>

<script type="module">
  import EmbedPDF from 'https://cdn.jsdelivr.net/npm/@embedpdf/viewer@3/dist/embedpdf.js';

  EmbedPDF.init({
    target: '#viewer',
    src: '/report.pdf',
    theme: 'dark',
    disable: ['redaction', 'documents.print'],
    onReady: (viewer) => console.log('ready', viewer),
  });
</script>

• No config prop. Each key is a prop of its own. A config you keep in an object still works: spread it into the viewer, as in the Quick start. In plain HTML, init() still takes the whole config, without type: 'container', and target can be a selector.
• onReady gives you the viewer, not the plugin registry. See From code.
• The viewer is one element, <embedpdf-viewer>. 2.x’s framework packages put an <embedpdf-container> inside a <div> of their own. Now there’s no <div>: your class and style go on the viewer itself.
• Five keys follow their prop: src, theme, locale, disable and readOnly. 2.x’s framework packages read the config once. Every other key is still read once: see Change the config later.
• Server-side rendering needs no wrapper. Every framework package is safe to import on the server, so a <ClientOnly> or a dynamic import around the viewer can go. See Setup.

The config, key by key#

Plugin settings#

The plugins’ settings are new too. plugins takes them under the 3.0 plugin’s name, as its page in the headless docs lists them, with plain strings where 2.x had enums. The ones 2.x apps set most:

All of them in one 3.0 config:

{
  plugins: {
    stage: {
      zoom: { mode: 'fit-width' },
      layout: 'horizontal',
      gap: 20,
      spread: 'odd',
      viewRotation: 90,
    },
    interaction: { defaultTool: 'pan' },
    thumbnails: { zoom: { pageWidth: 120 } },
    annotation: { afterCreate: { select: false, tool: 'default' } },
    stamp: { standard: false },
  },
}

Plugins links each plugin to its settings.

From code#

<!-- 2.x:

<button id="print">Print</button>
<div id="pdf-viewer" style="height: 80vh"></div>

<script type="module">
  import EmbedPDF from 'https://cdn.jsdelivr.net/npm/@embedpdf/snippet@2/dist/embedpdf.js';

  const container = EmbedPDF.init({
    type: 'container',
    target: document.getElementById('pdf-viewer'),
    src: '/report.pdf',
  });
  const registry = await container.registry;

  document.getElementById('print').onclick = () =>
    registry.getPlugin('commands').provides().execute('document:print');
</script>
-->

<button id="print" disabled>Print</button>
<div id="viewer" style="height: 80vh"></div>

<script type="module">
  import EmbedPDF from 'https://cdn.jsdelivr.net/npm/@embedpdf/viewer@3/dist/embedpdf.js';

  const print = document.getElementById('print');

  EmbedPDF.init({
    target: '#viewer',
    src: '/report.pdf',
    onReady: (viewer) => {
      print.disabled = false;
      print.onclick = () => viewer.commands.execute('document:print');
    },
  });
</script>

onReady gives you the viewer once it’s live. viewer.get('search') is what registry.getPlugin('search').provides() gave you in 2.x, and viewer.documents and viewer.commands need no call at all.

The plugins have new names:

Their methods are new as well, each on its plugin’s page in the headless docs. The calls 2.x code makes most:

Theme#

2.x set colors per mode, in groups: theme.light.accent.primary. 3.0 has one set of tokens for both modes, and dark for what’s different in dark mode:

{
  theme: {
    preference: 'system',
    accent: '#9333ea',
    tokens: { canvas: '#f5f3ff' },
    dark: { accent: '#a855f7', canvas: '#1e1b2e' },
  },
}

2.x’s light colors go in tokens, and its dark ones in dark:

The other 2.x colors, such as accent.primaryHover or state.error, have no token. For what tokens don’t cover, restyle a part with ::part(): see Theming. The container’s setTheme() is the theme prop now, which follows its value.

Buttons and the toolbar#

2.x changed the toolbar after the viewer started: registerCommand(), registerIcon(), then mergeSchema() with a copy of the toolbar’s items. In 3.0 all three are config, and the layout is a function that gets the default and returns yours. Here is 2.x’s example, a smiley in place of the comments button:

{
  icons: {
    smiley: [
      'M3 12a9 9 0 1 0 18 0a9 9 0 1 0 -18 0',
      'M9 10l.01 0',
      'M15 10l.01 0',
      'M9.5 15a3.5 3.5 0 0 0 5 0',
    ],
  },
  commands: [{ id: 'acme:hello', label: 'Say hello', icon: 'smiley', run: () => alert('Hello!') }],
  layout: (layout) => layout.replace('panel:comments', 'acme:hello'),
}

A command’s label, labelKey, icon, active, visible and categories keep their names. The ids changed:

Every 3.0 id is on Layout and Buttons & commands.

Turn features off#

disabledCategories is disable. It takes 3.0’s features, with their parts after a dot, and single commands by their id:

New in 3.0, readOnly: true turns off everything that changes the document.

Permissions#

2.x’s permissions changed what the viewer offered. 3.0’s scope is the list of what the user may do, and the engine checks it on every call:

2.x’s print is doc.print in a scope, printHighQuality is doc.print.high, copyContents is doc.text.copy, modifyAnnotations is doc.annotate.modify, fillForms is doc.forms.fill and assembleDocument is doc.pages.assemble. See Permissions.

Security and self-hosting#

Nothing from a third party#

2.x fetched several files from public servers. 3.0 fetches nothing from a third party unless you point it there:

So a PDF whose text needs a font it doesn’t embed, such as Chinese or Japanese, needs a fallback font you give the engine: see Fonts. Every file and its setting is on Self-hosting.

Content Security Policy#

2.x drew its styles from a <style> element in its shadow root, so a strict policy needed style-src 'unsafe-inline', and it started the engine’s workers from blob: URLs. 3.0 needs no 'unsafe-inline' or 'unsafe-eval' and runs with Trusted Types on. Installed from npm, its workers are files of your build, under worker-src 'self'; from the CDN they still start from blob: URLs. The policy to copy is on Security & CSP.

The page around it#

• 2.x added its font stylesheets to your page’s <head>. 3.0 adds nothing to your page: its styles stay in its own shadow DOM.
• Menus and tooltips open in the browser’s top layer, so your page’s headers never cover them, while panels and dialogs stay inside the viewer’s box. See How it works.
• 3.0 needs Chrome and Edge 114, Firefox 125 or Safari 17, or newer: see Setup.

Not in 3.0#

What 2.x had that 3.0 doesn’t:

• Loading in parts. 2.x’s mode: 'range-request' fetched a big file a piece at a time. The built-in engine downloads the whole file first: see Big files.
• Request options. For headers or credentials (requestOptions), fetch the file yourself and give src its bytes or a File.
• A limit on open documents (maxDocuments).
• The engine on the page’s own thread (worker: false), and its log (log). The engine always runs in a worker.
• Zoom limits and steps: minZoom, maxZoom, zoomStep, zoomRanges and presets.
• Marquee zoom, and the screenshot tool (the capture plugin).
• Protect. 2.x’s Protect dialog, setDocumentEncryption() and removeEncryption(): 3.0 can’t add or remove a document’s password.
• The outline and attachments panels, for now. The engine doesn’t read a document’s outline yet, and no plugin lists its attached files, so these two panels don’t show (2.x’s bookmark and attachment plugins).
• Swedish and Traditional Chinese. They aren’t built in: add them with strings.
• Theme events: themechange, activeColorScheme and themePreference.
• A few settings: export.defaultFileName, fullscreen.targetElement, i18n.fallbackLocale (English is the fallback) and i18n.paramResolvers.

Next steps#