Opening documents

Give the viewer the documents to open when it starts, and <DocumentGate> shows your content once the document is ready:

initial-documents.svelte

<script lang="ts">
  import { DocumentGate, Viewer } from '@embedpdf/svelte/runtime';
  import { RenderLayer } from '@embedpdf/svelte/render';
  import { Stage } from '@embedpdf/svelte/stage';
  import { engine, plugins } from './pdf';
  import Spinner from './Spinner.svelte';
</script>

<Viewer
  {engine}
  {plugins}
  initialDocuments={[{ source: { kind: 'url', url: '/files/contract.pdf' } }]}
>
  <DocumentGate>
    {#snippet fallback()}
      <Spinner />
    {/snippet}
    <Stage>
      <RenderLayer />
    </Stage>
  </DocumentGate>
</Viewer>

The viewer is on screen at once; the document opens in the background. Components outside <DocumentGate>, such as your toolbar’s frame, render right away.

Open a document later#

useDocuments() opens documents while the app runs, for example one the user picked:

open-button.svelte

<script lang="ts">
  import { useDocuments } from '@embedpdf/svelte/runtime';

  const documents = useDocuments();

  async function onPick(file: File) {
    await documents.open({ kind: 'bytes', bytes: await file.arrayBuffer() }, { name: file.name });
  }
</script>

<input
  type="file"
  accept="application/pdf"
  onchange={(event) => onPick(event.currentTarget.files![0])}
/>

open() resolves with { document } once it’s open, and the new document becomes the active one. Pass { activate: false } to open it in the background. Pick a PDF of your own here:

Loading live preview…

<script lang="ts" module>
  import { DocumentGate, Viewer, type OpenInput } from '@embedpdf/svelte/runtime';
  import { RenderLayer, renderPlugin } from '@embedpdf/svelte/render';
  import { Stage, stagePlugin } from '@embedpdf/svelte/stage';
  import { localEngine } from '@embedpdf/engine';
  import Empty from './Empty.svelte';
  import Toolbar from './Toolbar.svelte';

  import '../open.css';

  const engine = localEngine();
  const plugins = [stagePlugin(), renderPlugin()];

  const ebook = async (): Promise<OpenInput> => {
    const response = await fetch('https://snippet.embedpdf.com/ebook.pdf');
    return { kind: 'bytes', bytes: new Uint8Array(await response.arrayBuffer()) };
  };
</script>

<Viewer {engine} {plugins} initialDocuments={[{ source: ebook, name: 'ebook.pdf' }]}>
  <Toolbar {ebook} />
  <DocumentGate>
    {#snippet fallback()}
      <Empty />
    {/snippet}
    <Stage class="stage">
      <RenderLayer />
    </Stage>
  </DocumentGate>
</Viewer>

Where a document comes from#

Source	What it is
`{ kind: 'url', url }`	A file the viewer fetches. The URL can be relative to your site.
`{ kind: 'bytes', bytes }`	A file you already have: an upload, a file picker, a download.
`async (signal) => source`	Anything else: a function that returns one of the above.

A function is how you add your own fetch, such as one with a login header. The viewer calls it under the document’s loading state, and signal cancels the download if the user closes the document first:

const source = async (signal: AbortSignal) => {
  const response = await fetch(`/api/files/${id}`, { headers: { authorization }, signal });
  return { kind: 'bytes', bytes: await response.arrayBuffer() };
};

Loading, errors and passwords#

<DocumentGate> has something to show for each state a document can be in:

gate-states.svelte

<script lang="ts">
  import { DocumentGate } from '@embedpdf/svelte/runtime';
  import { RenderLayer } from '@embedpdf/svelte/render';
  import { Stage } from '@embedpdf/svelte/stage';
  import PasswordForm from './PasswordForm.svelte';
  import Spinner from './Spinner.svelte';
</script>

<DocumentGate>
  {#snippet fallback()}
    <Spinner />
  {/snippet}
  {#snippet locked(document)}
    <PasswordForm {document} />
  {/snippet}
  {#snippet error(document)}
    <p>Couldn't open {document.name}: {document.error.message}</p>
  {/snippet}
  <Stage>
    <RenderLayer />
  </Stage>
</DocumentGate>

A password-protected PDF opens locked. Ask for the password and unlock it:

password-form.svelte

<script lang="ts">
  import { useDocuments, type DocumentInfo } from '@embedpdf/svelte/runtime';
  import PasswordPrompt from './PasswordPrompt.svelte';

  let { document }: { document: DocumentInfo } = $props();
  const documents = useDocuments();
  let wrong = $state(false);

  async function submit(password: string) {
    try {
      await documents.unlock(document.id, { password });
    } catch {
      wrong = true; // it stays locked; ask again
    }
  }
</script>

<PasswordPrompt onSubmit={submit} {wrong} />

After an error, such as a network failure, documents.retry(id) tries again. Here the second document isn’t a PDF, so it shows its error:

Loading live preview…

<script lang="ts" module>
  import { DocumentGate, Viewer, type OpenInput } from '@embedpdf/svelte/runtime';
  import { RenderLayer, renderPlugin } from '@embedpdf/svelte/render';
  import { Stage, stagePlugin } from '@embedpdf/svelte/stage';
  import { localEngine } from '@embedpdf/engine';
  import OpenError from './OpenError.svelte';
  import PasswordForm from './PasswordForm.svelte';
  import Tabs from './Tabs.svelte';

  import '../states.css';

  const engine = localEngine();
  const plugins = [stagePlugin(), renderPlugin()];

  const ebook = async (): Promise<OpenInput> => {
    const response = await fetch('https://snippet.embedpdf.com/ebook.pdf');
    return { kind: 'bytes', bytes: new Uint8Array(await response.arrayBuffer()) };
  };

  // A file that isn't a PDF, so its document can't be opened.
  const broken: OpenInput = { kind: 'bytes', bytes: new TextEncoder().encode('Not a PDF') };
</script>

<Viewer
  {engine}
  {plugins}
  initialDocuments={[
    { source: ebook, name: 'ebook.pdf' },
    { source: broken, name: 'broken.pdf', active: true },
  ]}
>
  <Tabs />
  <DocumentGate>
    {#snippet fallback()}
      <div class="panel">Opening…</div>
    {/snippet}
    {#snippet locked(document)}
      <PasswordForm {document} />
    {/snippet}
    {#snippet error(document)}
      <OpenError {document} />
    {/snippet}
    <Stage class="stage">
      <RenderLayer />
    </Stage>
  </DocumentGate>
</Viewer>

To show the state yourself, for example on a tab, useDocument() gives you the document’s status: 'loading', 'locked', 'ready' or 'error'. Every field is listed under State.

Who the user is and what they may do#

Tell the viewer who the user is and what they may do, once. Every document it opens uses them:

identity-scope.svelte

<script lang="ts">
  import { Viewer } from '@embedpdf/svelte/runtime';
  import { engine, plugins } from './pdf';

  const identity = { userId: 'u_381', displayName: 'Dana Smith' };
  const scope = ['doc.open', 'doc.render', 'doc.text.select', 'doc.annotate.read', 'annotations:create:self'];
</script>

<Viewer {engine} {plugins} {identity} {scope} />

identity is who the user is. Their displayName becomes the author of the annotations they make.
scope is what they may do, as a list of permissions. Leave it out and they may do what the file allows: everything, unless the PDF restricts itself, as in Acrobat.

Loading live preview…

<script lang="ts" module>
  import { DocumentGate, Viewer, type OpenInput } from '@embedpdf/svelte/runtime';
  import { RenderLayer, renderPlugin } from '@embedpdf/svelte/render';
  import { Stage, stagePlugin } from '@embedpdf/svelte/stage';
  import { localEngine } from '@embedpdf/engine';
  import { dana, roles, type Role } from './roles';
  import Toolbar from './Toolbar.svelte';

  import '../identity.css';

  const engine = localEngine();
  const plugins = [stagePlugin(), renderPlugin()];

  const ebook = async (): Promise<OpenInput> => {
    const response = await fetch('https://snippet.embedpdf.com/ebook.pdf');
    return { kind: 'bytes', bytes: new Uint8Array(await response.arrayBuffer()) };
  };
</script>

<script lang="ts">
  let role = $state<Role>('reader');
</script>

<Viewer
  {engine}
  {plugins}
  identity={dana}
  scope={roles[role]}
  initialDocuments={[{ source: ebook, name: 'ebook.pdf' }]}
>
  <Toolbar bind:role {ebook} />
  <DocumentGate>
    {#snippet fallback()}
      <p class="loading">Opening…</p>
    {/snippet}
    <Stage class="stage">
      <RenderLayer />
    </Stage>
  </DocumentGate>
</Viewer>

Change them on the viewer, and the documents you open after that use the new values; documents already open keep theirs.

A document can have its own, which replace the viewer’s for that document:

const initialDocuments = [{ source, scope: ['doc.open', 'doc.render'] }]; // this one is read-only
await documents.open(source, { scope: ['doc.open', 'doc.render'] }); // and so is this one

Permissions lists every permission.

Close a document#

await documents.close(document.id);

Closing frees the document’s memory in the engine. The next document becomes the active one.

Methods#

What useDocuments() gives you for opening and closing documents and reading their pages. Tabs and the active document are on Several documents, downloading and printing on Saving & downloading.

Method	What it does
`open(source, options?)`	Opens a document and makes it the active one. Resolves `{ document }` once it’s ready, or locked with a password; rejects when it can’t be opened. Open a document later
`canOpenFiles()`	Whether `open()` takes a file’s bytes, such as a file the user picked, or a URL it downloads: `true` on the local engine, `false` on CloudPDF, where every document comes from your server
`openAll(documents)`	Opens several documents, as `initialDocuments` does: every tab appears at once, in order, and the one marked `active` (or the first) becomes the active one. A failure shows in that document’s `status` instead of throwing.
`unlock(id, { password })`	Unlocks a locked document. Rejects on a wrong password, and the document stays locked so you can ask again. Loading, errors and passwords
`retry(id)`	Tries a failed document again, with the same source and options. Resolves like `open()`.
`close(id)`, `closeAll()`	Closes one document, or every document, and frees its memory. Close a document
`get(id?)`	A document’s fields, the ones `useDocument()` gives you, or `null` when it isn’t open. Without an `id`, the document in scope
`listPages(id?)`	The document’s pages, in order. In a component, use `usePageList()`.
`getPage(page, id?)`	One page, by its `ref` or its index, or `null` when the document doesn’t have it
`getPageIndex(ref, id?)`	A page’s position, from 0, or `-1` when the document doesn’t have it
`getRevision(id?)`	A number that goes up each time pages are added, removed, moved or rotated; `-1` with no document

options for open() are name (what its tab shows), activate: false (open it in the background), password, and, on the local engine, scope and identity. Without an id, the page methods use the document in scope: the one a <DocumentScope> around your component names, or else the active one. To stop an open that’s still loading, close the document: that cancels its download too.

State#

useDocument() gives you the document a component talks to: the active one, or the one its <DocumentScope> names. It’s one reactive object: read its fields, and your markup updates when they change. Outside a component, get(id) gives the same fields. With no document open yet, it reads as one still on its way: an empty id and status: 'loading', so a component that shows it never has to check for null.

Field	What it is
`id`	The document’s id, for `close(id)`, `unlock(id, …)` and `<DocumentScope>`
`name`	The name its tab shows, from `open()` or `rename()`
`status`	`'loading'`, `'locked'`, `'ready'` or `'error'`
`pageCount`	How many pages it has; `0` until it’s ready
`hasUnsavedChanges`	Whether it has changes that weren’t downloaded yet. Warn before changes are lost
`passwordProvided`	When it’s locked: whether a password was tried and was wrong
`error`	Why it couldn’t be opened, when `status` is `'error'`: `{ code, message }`

Every open document, with the same fields, comes from useDocumentsState().

Events#

open-failed.svelte

<script lang="ts">
  import { useDocumentsEvent } from '@embedpdf/svelte/runtime';

  let message = $state('');

  useDocumentsEvent(
    (documents) => documents.onOpenFailed,
    ({ error }) => (message = `Couldn't open the file: ${error.message}`),
  );
</script>

<p role="alert">{message}</p>

Event	Fires when	Carries
`onOpened`	A document is open and ready	`documentId`, `info`
`onOpenFailed`	A document couldn’t be opened	`documentId`, `error`
`onLocked`	A document needs a password	`documentId`, `passwordProvided`
`onClosed`	A document was closed	`documentId`
`onPagesChanged`	Pages were added, removed, moved or rotated	`documentId`, `pages`, `revision`

Switching the active document is on Several documents.

Good to know#

Opening large files#

The local engine needs the whole file before it can show the first page, so a large PDF on a slow connection takes as long as its download.

`initialDocuments` is read once#

Like engine and plugins, the viewer reads initialDocuments when it mounts. To open another document later, use documents.open().

Several documents#

A viewer can hold several documents at once, like tabs. See Several documents.

Was this page helpful?

Your feedback goes directly to the documentation team.

Opening documents

Open a document later#

Where a document comes from#

Loading, errors and passwords#

Who the user is and what they may do#

Close a document#

Methods#

State#

Events#

Good to know#

Opening large files#

initialDocuments is read once#

Several documents#

`initialDocuments` is read once#