---
title: "Opening documents — React"
description: "Open PDFs in the viewer, show loading states and errors, ask for passwords, and say who the user is and what they may do."
framework: "React"
source: "https://www.embedpdf.com/docs/headless/react/documents/opening"
---

# Opening documents

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

**`initial-documents.tsx`**

```tsx
import { DocumentGate, Viewer } from '@embedpdf/react/runtime';
import { RenderLayer } from '@embedpdf/react/render';
import { Stage } from '@embedpdf/react/stage';
import { engine, plugins } from './pdf';
import { Spinner } from './Spinner';

export function ContractViewer() {
  return (
    <Viewer
      engine={engine}
      plugins={plugins}
      initialDocuments={[{ source: { kind: 'url', url: '/files/contract.pdf' } }]}
    >
      <DocumentGate fallback={<Spinner />}>
        <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.tsx`**

```tsx
import { useDocuments } from '@embedpdf/react/runtime';

export function OpenButton() {
  const documents = useDocuments();

  const onPick = async (file: File) => {
    await documents.open({ kind: 'bytes', bytes: await file.arrayBuffer() }, { name: file.name });
  };

  return <input type="file" accept="application/pdf" onChange={(e) => onPick(e.target.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:

**`open.tsx`**

```tsx
import { Viewer, DocumentGate, useDocument, useDocuments } from '@embedpdf/react/runtime';
import type { OpenInput } from '@embedpdf/react/runtime';
import { Stage, stagePlugin } from '@embedpdf/react/stage';
import { RenderLayer, renderPlugin } from '@embedpdf/react/render';
import { localEngine } from '@embedpdf/engine';

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()) };
};

function Toolbar() {
  const documents = useDocuments();
  const { id, name, status, pageCount } = useDocument();

  // A file the user picks opens next to the ebook, and becomes the active document.
  const openFile = async (file: File) => {
    await documents.open({ kind: 'bytes', bytes: await file.arrayBuffer() }, { name: file.name });
  };

  return (
    <div className="toolbar">
      <span className="document">
        {id ? (
          <>
            <strong>{name ?? 'Untitled'}</strong>
            {status === 'ready' ? ` · ${pageCount} pages` : ` · ${status}`}
          </>
        ) : (
          'No document open'
        )}
      </span>
      <label className="button picker">
        Open a PDF…
        <input
          type="file"
          accept="application/pdf"
          onChange={(event) => {
            const file = event.target.files?.[0];
            if (file) void openFile(file);
            event.target.value = '';
          }}
        />
      </label>
      {id ? (
        <button type="button" className="button" onClick={() => documents.close(id)}>
          Close
        </button>
      ) : (
        <button
          type="button"
          className="button"
          onClick={() => documents.open(ebook, { name: 'ebook.pdf' })}
        >
          Open the ebook again
        </button>
      )}
    </div>
  );
}

// The gate's fallback: a document on its way, or none at all.
function Empty() {
  const { id } = useDocument();
  return (
    <p className="loading">{id ? 'Opening…' : 'No document is open. Open a PDF to see it here.'}</p>
  );
}

export default function App() {
  return (
    <Viewer
      engine={engine}
      plugins={plugins}
      initialDocuments={[{ source: ebook, name: 'ebook.pdf' }]}
    >
      <Toolbar />
      <DocumentGate fallback={<Empty />}>
        <Stage className="stage">{() => <RenderLayer />}</Stage>
      </DocumentGate>
    </Viewer>
  );
}
```

**`open.css`**

```css
/* Colors */
:root {
  --ink: #1a2748;
  --muted: #5a6b92;
  --line: #e6eaf2;
  --line-strong: #dce8fc;
  --surface: #ffffff;
  --tint: #f3f7fe;
  --canvas: #f7f9fc;
  --focus: #7db6ff;
  --shadow: rgb(7 32 76 / 0.04);
}

/* The bar above the pages: the open document, and the buttons */
.toolbar {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 8px;
  margin-bottom: 14px;
}

.document {
  flex: 1 1 200px;
  min-width: 0;
  font-size: 13px;
  color: var(--muted);
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

.document strong {
  color: var(--ink);
  font-weight: 600;
}

.button {
  font: inherit;
  font-size: 13px;
  font-weight: 550;
  color: var(--ink);
  background: var(--surface);
  border: 1px solid var(--line);
  border-radius: 9px;
  padding: 8px 12px;
  cursor: pointer;
  box-shadow: 0 1px 2px var(--shadow);
  transition:
    background-color 0.15s ease,
    border-color 0.15s ease;
}

.button:hover {
  background: var(--tint);
  border-color: var(--line-strong);
}

.button:disabled {
  opacity: 0.45;
  cursor: not-allowed;
}

.button:focus-within,
.button:focus-visible {
  outline: 2px solid var(--focus);
  outline-offset: 2px;
}

/* The file input sits invisibly inside its label, which looks like a button */
.picker input {
  position: absolute;
  width: 1px;
  height: 1px;
  opacity: 0;
}

/* The pages */
.stage {
  height: 420px;
  border: 1px solid var(--line);
  border-radius: 14px;
  background: var(--canvas);
  box-shadow:
    0 1px 2px var(--shadow),
    0 18px 40px -28px rgb(7 32 76 / 0.28);
}

.loading {
  margin: 0;
  padding: 24px 0;
  text-align: center;
  font-size: 13px;
  color: var(--muted);
}
```

## 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:

```ts
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.tsx`**

```tsx
import { DocumentGate } from '@embedpdf/react/runtime';
import { RenderLayer } from '@embedpdf/react/render';
import { Stage } from '@embedpdf/react/stage';
import { PasswordForm } from './PasswordForm';
import { Spinner } from './Spinner';

export function DocumentView() {
  return (
    <DocumentGate
      fallback={<Spinner />}
      locked={(document) => <PasswordForm document={document} />}
      error={(document) => <p>Couldn’t open {document.name}: {document.error.message}</p>}
    >
      <Stage>{() => <RenderLayer />}</Stage>
    </DocumentGate>
  );
}
```

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

**`password-form.tsx`**

```tsx
import { useState } from 'react';
import { useDocuments, type DocumentInfo } from '@embedpdf/react/runtime';
import { PasswordPrompt } from './PasswordPrompt';

export function PasswordForm({ document }: { document: DocumentInfo }) {
  const documents = useDocuments();
  const [wrong, setWrong] = useState(false);

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

  return <PasswordPrompt onSubmit={submit} wrong={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:

**`states.tsx`**

```tsx
import { useState } from 'react';
import {
  Viewer,
  DocumentGate,
  useDocuments,
  useDocumentsState,
  type DocumentInfo,
  type FailedDocumentInfo,
} from '@embedpdf/react/runtime';
import type { OpenInput } from '@embedpdf/react/runtime';
import { Stage, stagePlugin } from '@embedpdf/react/stage';
import { RenderLayer, renderPlugin } from '@embedpdf/react/render';
import { localEngine } from '@embedpdf/engine';

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') };

function Tabs() {
  const documents = useDocuments();
  const { documents: open, activeId } = useDocumentsState();

  return (
    <div className="tabs" role="tablist">
      {open.map((document) => (
        <button
          key={document.id}
          type="button"
          role="tab"
          className="tab"
          aria-selected={document.id === activeId}
          onClick={() => documents.setActive(document.id)}
        >
          <span className="status" data-status={document.status} />
          {document.name}
        </button>
      ))}
    </div>
  );
}

function PasswordForm({ document }: { document: DocumentInfo }) {
  const documents = useDocuments();
  const [password, setPassword] = useState('');
  const [wrong, setWrong] = useState(document.passwordProvided ?? false);

  const unlock = async () => {
    try {
      await documents.unlock(document.id, { password });
    } catch {
      setWrong(true); // it stays locked; ask again
    }
  };

  return (
    <div className="panel">
      <h3>{document.name} needs a password</h3>
      {wrong && <p>That password isn’t right. Try again.</p>}
      <div className="actions">
        <input
          className="field"
          type="password"
          aria-label="Password"
          value={password}
          onChange={(event) => setPassword(event.target.value)}
        />
        <button type="button" className="button" onClick={unlock}>
          Unlock
        </button>
      </div>
    </div>
  );
}

function OpenError({ document }: { document: FailedDocumentInfo }) {
  const documents = useDocuments();
  return (
    <div className="panel" data-tone="error">
      <h3>Couldn’t open {document.name}</h3>
      <p>{document.error.message}</p>
      <div className="actions">
        <button type="button" className="button" onClick={() => documents.retry(document.id)}>
          Try again
        </button>
        <button type="button" className="button" onClick={() => documents.close(document.id)}>
          Close
        </button>
      </div>
    </div>
  );
}

export default function App() {
  return (
    <Viewer
      engine={engine}
      plugins={plugins}
      initialDocuments={[
        { source: ebook, name: 'ebook.pdf' },
        { source: broken, name: 'broken.pdf', active: true },
      ]}
    >
      <Tabs />
      <DocumentGate
        fallback={<div className="panel">Opening…</div>}
        locked={(document) => <PasswordForm document={document} />}
        error={(document) => <OpenError document={document} />}
      >
        <Stage className="stage">{() => <RenderLayer />}</Stage>
      </DocumentGate>
    </Viewer>
  );
}
```

**`states.css`**

```css
/* Colors */
:root {
  --ink: #1a2748;
  --muted: #5a6b92;
  --line: #e6eaf2;
  --line-strong: #dce8fc;
  --surface: #ffffff;
  --tint: #f3f7fe;
  --canvas: #f7f9fc;
  --focus: #7db6ff;
  --danger: #b42318;
  --danger-tint: #fef3f2;
  --shadow: rgb(7 32 76 / 0.04);
}

/* The tabs: one per document, with its status */
.tabs {
  display: flex;
  flex-wrap: wrap;
  gap: 6px;
  margin-bottom: 14px;
}

.tab {
  display: inline-flex;
  align-items: center;
  gap: 8px;
  font: inherit;
  font-size: 13px;
  font-weight: 550;
  color: var(--muted);
  background: var(--surface);
  border: 1px solid var(--line);
  border-radius: 9px;
  padding: 7px 12px;
  cursor: pointer;
  box-shadow: 0 1px 2px var(--shadow);
}

.tab[aria-selected='true'] {
  color: var(--ink);
  background: var(--tint);
  border-color: var(--focus);
}

.tab:focus-visible {
  outline: 2px solid var(--focus);
  outline-offset: 2px;
}

/* The dot before a tab's name: its status */
.status {
  width: 8px;
  height: 8px;
  border-radius: 50%;
  background: var(--line-strong);
}

.status[data-status='ready'] {
  background: #12b76a;
}

.status[data-status='loading'] {
  background: var(--focus);
}

.status[data-status='locked'] {
  background: #f79009;
}

.status[data-status='error'] {
  background: var(--danger);
}

/* What the gate shows instead of the pages */
.panel {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  gap: 12px;
  height: 420px;
  box-sizing: border-box;
  padding: 24px;
  text-align: center;
  font-size: 13px;
  color: var(--muted);
  border: 1px solid var(--line);
  border-radius: 14px;
  background: var(--canvas);
}

.panel h3 {
  margin: 0;
  font-size: 15px;
  color: var(--ink);
}

.panel p {
  margin: 0;
  max-width: 360px;
}

.panel[data-tone='error'] {
  background: var(--danger-tint);
}

.panel[data-tone='error'] p {
  color: var(--danger);
}

.actions {
  display: flex;
  flex-wrap: wrap;
  justify-content: center;
  gap: 8px;
}

.field {
  appearance: none;
  min-width: 0;
  font: inherit;
  font-size: 13px;
  color: var(--ink);
  background: var(--surface);
  border: 1px solid var(--line);
  border-radius: 9px;
  padding: 8px 12px;
}

.button {
  font: inherit;
  font-size: 13px;
  font-weight: 550;
  color: var(--ink);
  background: var(--surface);
  border: 1px solid var(--line);
  border-radius: 9px;
  padding: 8px 12px;
  cursor: pointer;
  box-shadow: 0 1px 2px var(--shadow);
}

.button:hover {
  background: var(--tint);
  border-color: var(--line-strong);
}

.button:focus-visible,
.field:focus-visible {
  outline: 2px solid var(--focus);
  outline-offset: 2px;
}

/* The pages */
.stage {
  height: 420px;
  border: 1px solid var(--line);
  border-radius: 14px;
  background: var(--canvas);
  box-shadow:
    0 1px 2px var(--shadow),
    0 18px 40px -28px rgb(7 32 76 / 0.28);
}
```

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](#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.tsx`**

```tsx
import { Viewer } from '@embedpdf/react/runtime';
import { engine, plugins } from './pdf';

export function ReviewViewer() {
  return (
    <Viewer
      engine={engine}
      plugins={plugins}
      identity={{ userId: 'u_381', displayName: 'Dana Smith' }}
      scope={['doc.open', 'doc.render', 'doc.text.select', 'doc.annotate.read', 'annotations:create:self']}
    />
  );
}
```

- **`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.

**`identity.tsx`**

```tsx
import { useState } from 'react';
import { Viewer, DocumentGate, useDocument, useDocuments } from '@embedpdf/react/runtime';
import type { OpenInput } from '@embedpdf/react/runtime';
import { Stage, stagePlugin } from '@embedpdf/react/stage';
import { RenderLayer, renderPlugin } from '@embedpdf/react/render';
import { localEngine } from '@embedpdf/engine';

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()) };
};

const dana = { userId: 'u_381', displayName: 'Dana Smith' };

// What each role may do, as permissions.
const roles = {
  reader: ['doc.open', 'doc.render', 'doc.text.select'],
  editor: [
    'doc.open',
    'doc.render',
    'doc.text.select',
    'doc.text.copy',
    'doc.download',
    'doc.print',
  ],
};
type Role = keyof typeof roles;

function Toolbar({ role, onRoleChange }: { role: Role; onRoleChange: (role: Role) => void }) {
  const documents = useDocuments();
  // Read the document too, so the checks are read again when it opens or closes.
  const { id } = useDocument();
  // The role the open document was opened with: it keeps that one.
  const [openedAs, setOpenedAs] = useState(role);

  const openAgain = async () => {
    await documents.close(id);
    await documents.open(ebook, { name: 'ebook.pdf' });
    setOpenedAs(role);
  };

  return (
    <>
      <div className="toolbar">
        <label className="label">
          Dana Smith, as
          <select
            className="select"
            value={role}
            onChange={(event) => onRoleChange(event.target.value as Role)}
          >
            <option value="reader">reader</option>
            <option value="editor">editor</option>
          </select>
        </label>
        <span className="check" data-allowed={documents.canDownload()}>
          Download
        </span>
        <span className="check" data-allowed={documents.canPrint()}>
          Print
        </span>
      </div>
      <p className="note">
        This document opened for a {openedAs}.
        {openedAs !== role && (
          <button type="button" className="button" onClick={openAgain}>
            Open it again as {role}
          </button>
        )}
      </p>
    </>
  );
}

export default function App() {
  const [role, setRole] = useState<Role>('reader');
  return (
    <Viewer
      engine={engine}
      plugins={plugins}
      identity={dana}
      scope={roles[role]}
      initialDocuments={[{ source: ebook, name: 'ebook.pdf' }]}
    >
      <Toolbar role={role} onRoleChange={setRole} />
      <DocumentGate fallback={<p className="loading">Opening…</p>}>
        <Stage className="stage">{() => <RenderLayer />}</Stage>
      </DocumentGate>
    </Viewer>
  );
}
```

**`identity.css`**

```css
/* Colors */
:root {
  --ink: #1a2748;
  --muted: #5a6b92;
  --line: #e6eaf2;
  --line-strong: #dce8fc;
  --surface: #ffffff;
  --tint: #f3f7fe;
  --canvas: #f7f9fc;
  --focus: #7db6ff;
  --allowed: #067647;
  --allowed-tint: #ecfdf3;
  --refused: #b42318;
  --refused-tint: #fef3f2;
  --shadow: rgb(7 32 76 / 0.04);
}

/* Who is signed in, and what the open document allows */
.toolbar {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 8px;
  margin-bottom: 8px;
  font-size: 13px;
  color: var(--ink);
}

.label {
  display: inline-flex;
  align-items: center;
  gap: 6px;
  margin-right: auto;
}

.select {
  font: inherit;
  font-size: 13px;
  color: var(--ink);
  background: var(--surface);
  border: 1px solid var(--line);
  border-radius: 9px;
  padding: 7px 10px;
}

/* A check's answer: green when the document allows it, red when it doesn't */
.check {
  font-size: 12px;
  font-weight: 600;
  border-radius: 999px;
  padding: 4px 10px;
}

.check[data-allowed='true'] {
  color: var(--allowed);
  background: var(--allowed-tint);
}

.check[data-allowed='false'] {
  color: var(--refused);
  background: var(--refused-tint);
}

.note {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 8px;
  min-height: 34px;
  margin: 0 0 14px;
  font-size: 13px;
  color: var(--muted);
}

.button {
  font: inherit;
  font-size: 13px;
  font-weight: 550;
  color: var(--ink);
  background: var(--surface);
  border: 1px solid var(--line);
  border-radius: 9px;
  padding: 7px 12px;
  cursor: pointer;
  box-shadow: 0 1px 2px var(--shadow);
}

.button:hover {
  background: var(--tint);
  border-color: var(--line-strong);
}

.button:focus-visible,
.select:focus-visible {
  outline: 2px solid var(--focus);
  outline-offset: 2px;
}

/* The pages */
.stage {
  height: 400px;
  border: 1px solid var(--line);
  border-radius: 14px;
  background: var(--canvas);
  box-shadow:
    0 1px 2px var(--shadow),
    0 18px 40px -28px rgb(7 32 76 / 0.28);
}

.loading {
  margin: 0;
  padding: 24px 0;
  text-align: center;
  font-size: 13px;
  color: var(--muted);
}
```

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:

```ts
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](../concepts/permissions) lists every permission.

## Close a document

```ts
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](tabs#methods), downloading and printing on
[Saving & downloading](saving#methods).

| 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](#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](#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](#close-a-document)                                                                                                                           |
| `get(id?)`                 | A document's fields, the ones [`useDocument()`](#state) 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()`](../viewing/page-view#pick-the-page).                                                                                                                    |
| `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>`](tabs#talk-to-a-specific-document)
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. Your component re-renders when a value changes. 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](saving#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()`](tabs#state).

## Events

**`open-failed.tsx`**

```tsx
import { useState } from 'react';
import { useDocumentsEvent } from '@embedpdf/react/runtime';

export function OpenError() {
  const [message, setMessage] = useState('');

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

  return <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](tabs#events).

## 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.

> **Open a 500 MB PDF in a second**
>
> With CloudPDF, the file stays on your server. The viewer asks only for the pages on screen, as
> images, so the first page shows at once whatever the file's size, and a user who may not download
> the file never receives it.
>
> [Open documents with CloudPDF](https://www.cloudpdf.com/docs/headless/react/documents/opening)

### `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](tabs).