--- title: Setup description: Install the viewer, give it a size, pass it config, render on the server, and run several viewers on one page. --- import { Callout } from '@/components/docs/callout'; # Setup One package gives you the whole viewer: the toolbar and panels, the PDF engine, and everything the engine needs, served from your own site. One package gives you the whole viewer: the toolbar and panels, and the engine that opens your documents on CloudPDF. On a plain HTML page, load the script from jsDelivr as above. In an app with a bundler, install `@embedpdf/viewer` and `import '@embedpdf/viewer'` once, which defines the `` element. 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 `` 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](customize/small-screens). On a page that scrolls, a wheel over the viewer scrolls the pages, and at their end the next scroll goes on to your page. A viewer that fills the window has no page to scroll, so turn that off with `plugins: { stage: { scrollChaining: false } }`: see [Inside a page that scrolls](/docs/headless/viewing/stage#inside-a-page-that-scrolls). ## Pass it config Everything the viewer can do is one config object. In a framework, every key is a prop: On a plain HTML page, `init()` takes the config with a `target`, a selector or an element: it puts the viewer inside it and returns the `` element. Written as a tag, the element takes its config through its `config` property. Three keys can be attributes of the tag too: `src`, `locale` and `theme`. Two keys can be attributes of the tag too: `locale` and `theme`. | Key | What it is | Page | | :-- | :-- | :-- | | `src` | One document: a URL, a `File`, or bytes | [Documents](documents) | | `documents` | Several documents, shown as tabs | [Documents](documents#several-documents) | | `fetch` | Your own `fetch` for documents at a URL, to add headers or cookies | [Documents](documents#files-that-need-a-sign-in) | | `layout` | Where every toolbar, button, menu and panel goes | [Layout](customize/layout) | | `size` | `'auto'` (default), or the layout of one size at every width: `'compact'`, `'medium'` or `'expanded'` | [Small screens](customize/small-screens#one-size-at-every-width) | | `touch` | `'auto'` (default), or `true` or `false`: a finger's 44 px buttons on any pointer, or on none | [Small screens](customize/small-screens#touch) | | `commands` | Your own actions | [Buttons & commands](customize/commands) | | `appState` | Your app's state, which your commands read | [Buttons & commands](customize/commands#your-apps-state) | | `icons` | Your own icons | [Buttons & commands](customize/commands#icons) | | `theme` | `'light'`, `'dark'`, `'system'`, or your colors | [Theming](customize/theming) | | `locale` | `'auto'` or a language code | [Translations](customize/translations) | | `strings` | Your own words, and other languages | [Translations](customize/translations) | | `features` | What people can do: features on or off | [Turn features on and off](features/turning-off) | | `readOnly` | Every feature that changes the document off | [Turn features on and off](features/turning-off#read-only) | | `scope` | What the user may do, checked by the engine | [Turn features on and off](features/turning-off#what-a-user-may-do) | | `identity` | Who the user is: the author of their annotations | [All features](features#who-the-user-is) | | `notAllowed` | `'hide'` (default) or `'disable'` what the scope doesn't allow | [Turn features on and off](features/turning-off#what-a-user-may-do) | | `plugins` | The settings of each feature's plugin | [Plugins](code/plugins#settings) | | `fonts` | Your fonts, beyond the standard PDF fonts, for the text people write | [Fonts](features/fonts) | | `warnBeforeLeaving` | `true` (default), or `false` to leave the page without asking, unsaved changes or not | [Documents](documents#warn-before-changes-are-lost) | | `engine` | Where the engine's files come from, or another engine | [Self-hosting](self-hosting) | | `onReady` | Called with the `viewer` once it's live | [The viewer in code](code/viewer) | | `onDocumentChange` | Called with the document that's showing: the first one, each one the user switches to, and `null` after the last one closes | [Documents](documents#several-documents) | | `onPanelResize` | Called with a panel's id and width when the user resizes it | [Panels](customize/panels#keep-the-width-people-chose) | | Key | What it is | Page | | :-- | :-- | :-- | | `src` | One document: `{ token }`, `{ id }` or `{ grant }` | [Documents](documents) | | `documents` | Several documents, shown as tabs | [Documents](documents#several-documents) | | `layout` | Where every toolbar, button, menu and panel goes | [Layout](customize/layout) | | `size` | `'auto'` (default), or the layout of one size at every width: `'compact'`, `'medium'` or `'expanded'` | [Small screens](customize/small-screens#one-size-at-every-width) | | `touch` | `'auto'` (default), or `true` or `false`: a finger's 44 px buttons on any pointer, or on none | [Small screens](customize/small-screens#touch) | | `commands` | Your own actions | [Buttons & commands](customize/commands) | | `appState` | Your app's state, which your commands read | [Buttons & commands](customize/commands#your-apps-state) | | `icons` | Your own icons | [Buttons & commands](customize/commands#icons) | | `theme` | `'light'`, `'dark'`, `'system'`, or your colors | [Theming](customize/theming) | | `locale` | `'auto'` or a language code | [Translations](customize/translations) | | `strings` | Your own words, and other languages | [Translations](customize/translations) | | `features` | What people can do: features on or off | [Turn features on and off](features/turning-off) | | `readOnly` | Every feature that changes the document off | [Turn features on and off](features/turning-off#read-only) | | `notAllowed` | `'hide'` (default) or `'disable'` what the user's token doesn't allow | [Turn features on and off](features/turning-off#what-a-user-may-do) | | `plugins` | The settings of each feature's plugin | [Plugins](code/plugins#settings) | | `fonts` | Ignored on the cloud: your server's fonts are the ones offered | [Fonts](features/fonts) | | `engine` | Your own CloudPDF server (`baseUrl`), the engine's own `token`, or another engine | [Self-hosting](self-hosting) | | `onReady` | Called with the `viewer` once it's live | [The viewer in code](code/viewer) | | `onDocumentChange` | Called with the document that's showing: the first one, each one the user switches to, and `null` after the last one closes | [Documents](documents#several-documents) | | `onPanelResize` | Called with a panel's id and width when the user resizes it | [Panels](customize/panels#keep-the-width-people-chose) | 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](quick-start#3-make-it-yours). ## 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`: ```ts import type { ViewerConfig } from '@embedpdf/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: 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: ```js { src: { token: await fetchDocumentToken('contract-42') }, } ``` Pass a function, and the viewer asks it again a minute before each token expires: `src: { id: contract.documentId, token: () => fetchDocumentToken(contract.id) }`. See [Authentication](/docs/engine/authentication) for the ways to open a document and what a token carries. A cloud document is an object, not a URL, so on a plain HTML page it is given from script, never as the `src` attribute: `element.src = { token }`. ## Change the config later Six 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; `features` and `readOnly` take tools away or bring them back; `appState` gives [your commands](customize/commands#your-apps-state) your app's state as it is now. `fetch` follows its prop too: the next document at a URL downloads with the new one. On a plain HTML page, each of these keys is a property of the element too. Set one, and that key changes in place: ```js const element = document.querySelector('embedpdf-viewer'); element.theme = 'dark'; element.locale = 'de'; element.readOnly = true; ``` `element.config = { … }` replaces the whole config, and with it what the properties set: set them again after it, or put them in it. What the element's attributes say stays. Any plugin's settings change through the `viewer` (see [Plugins](code/plugins#settings)). Everything else is read once, when the viewer starts. To change it, mount a new viewer: 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 engine runs in a Web Worker, as WebAssembly. 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](concepts/security) has the policy to copy. ### Air-gapped and self-hosted Nothing is fetched from a third party at runtime unless you point the viewer there. See [Self-hosting](self-hosting) for every file and the setting that controls it. The viewer talks to one server: CloudPDF SaaS, or your own CloudPDF when `engine: { baseUrl }` names it. See [Self-hosting](self-hosting) for running your own and the files the browser loads. The viewer is built on the same packages as [headless](/docs/headless). Everything you set up here still applies if you build your own interface later.