---
title: "Opening documents — Angular"
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: "Angular"
source: "https://www.embedpdf.com/docs/headless/angular/documents/opening"
---

# Opening documents

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

**`initial-documents.ts`**

```typescript
import { Component } from '@angular/core';
import { EpdfDocumentGate, provideEmbedPdf } from '@embedpdf/angular/runtime';
import { EpdfRenderLayer, withRender } from '@embedpdf/angular/render';
import { EpdfPageTemplate, EpdfStage, withStage } from '@embedpdf/angular/stage';
import { engine } from './pdf';
import { Spinner } from './spinner';

@Component({
  selector: 'app-contract-viewer',
  imports: [EpdfDocumentGate, EpdfStage, EpdfPageTemplate, EpdfRenderLayer, Spinner],
  providers: [
    provideEmbedPdf(
      { engine, initialDocuments: [{ source: { kind: 'url', url: '/files/contract.pdf' } }] },
      withStage(),
      withRender(),
    ),
  ],
  template: `
    <epdf-stage *epdfDocumentGate="let document; fallback: opening">
      <ng-template epdfPage>
        <epdf-render-layer />
      </ng-template>
    </epdf-stage>

    <ng-template #opening><app-spinner /></ng-template>
  `,
})
export class ContractViewer {}
```

The viewer is on screen at once; the document opens in the background. Components outside
`*epdfDocumentGate`, such as your toolbar's frame, render right away.

## Open a document later

`inject(EpdfDocuments)` opens documents while the app runs, for example one the user picked:

**`open-button.ts`**

```typescript
import { Component, inject } from '@angular/core';
import { EpdfDocuments } from '@embedpdf/angular/runtime';

@Component({
  selector: 'app-open-button',
  template: `<input #picker type="file" accept="application/pdf" (change)="open(picker.files![0])" />`,
})
export class OpenButton {
  private readonly documents = inject(EpdfDocuments);

  protected async open(file: File) {
    await this.documents.open({ kind: 'bytes', bytes: await file.arrayBuffer() }, { name: file.name });
  }
}
```

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

```typescript
import { ChangeDetectionStrategy, Component, inject, ViewEncapsulation } from '@angular/core';
import {
  EpdfDocument,
  EpdfDocumentGate,
  EpdfDocuments,
  provideEmbedPdf,
} from '@embedpdf/angular/runtime';
import type { OpenInput } from '@embedpdf/angular/runtime';
import { EpdfPageTemplate, EpdfStage, withStage } from '@embedpdf/angular/stage';
import { EpdfRenderLayer, withRender } from '@embedpdf/angular/render';
import { localEngine } from '@embedpdf/engine';

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

@Component({
  selector: 'demo-root',
  imports: [EpdfDocumentGate, EpdfStage, EpdfPageTemplate, EpdfRenderLayer],
  providers: [
    provideEmbedPdf(
      { engine: () => localEngine(), initialDocuments: [{ source: ebook, name: 'ebook.pdf' }] },
      withStage(),
      withRender(),
    ),
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  styleUrl: './open.css',
  encapsulation: ViewEncapsulation.None,
  template: `
    <div class="toolbar">
      <span class="document">
        @if (document.id()) {
          <strong>{{ document.name() ?? 'Untitled' }}</strong>
          {{
            document.status() === 'ready'
              ? ' · ' + document.pageCount() + ' pages'
              : ' · ' + document.status()
          }}
        } @else {
          No document open
        }
      </span>
      <label class="button picker">
        Open a PDF…
        <input #picker type="file" accept="application/pdf" (change)="pick(picker)" />
      </label>
      @if (document.id()) {
        <button type="button" class="button" (click)="documents.close(document.id())">Close</button>
      } @else {
        <button type="button" class="button" (click)="documents.open(ebook, { name: 'ebook.pdf' })">
          Open the ebook again
        </button>
      }
    </div>

    <epdf-stage *epdfDocumentGate="let ready; fallback: empty" class="stage">
      <ng-template epdfPage>
        <epdf-render-layer />
      </ng-template>
    </epdf-stage>

    <!-- The gate's fallback: a document on its way, or none at all. -->
    <ng-template #empty>
      <p class="loading">
        {{ document.id() ? 'Opening…' : 'No document is open. Open a PDF to see it here.' }}
      </p>
    </ng-template>
  `,
})
export class App {
  protected readonly documents = inject(EpdfDocuments);
  protected readonly document = inject(EpdfDocument);
  protected readonly ebook = ebook;

  // A file the user picks opens next to the ebook, and becomes the active document.
  protected async pick(picker: HTMLInputElement) {
    const file = picker.files?.[0];
    picker.value = '';
    if (!file) return;
    await this.documents.open(
      { kind: 'bytes', bytes: await file.arrayBuffer() },
      { name: file.name },
    );
  }
}
```

**`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);
}
```

When an input or a route parameter names the document, give it to the Stage instead:
`<epdf-stage [document]="source()">` opens the document, and when the signal changes, it opens the
new one and closes the old one.

```ts
import { Component, computed, input } from '@angular/core';
import { EpdfRenderLayer } from '@embedpdf/angular/render';
import { EpdfPageTemplate, EpdfStage } from '@embedpdf/angular/stage';

@Component({
  selector: 'app-contract-page',
  imports: [EpdfStage, EpdfPageTemplate, EpdfRenderLayer],
  template: `
    <epdf-stage [document]="source()">
      <ng-template epdfPage>
        <epdf-render-layer />
      </ng-template>
    </epdf-stage>
  `,
})
export class ContractPage {
  /** `/contracts/:id`, bound with `withComponentInputBinding()` */
  readonly id = input.required<string>();
  protected readonly source = computed(() => ({ kind: 'url', url: `/files/${this.id()}.pdf` }) as const);
}
```

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

`*epdfDocumentGate` has something to show for each state a document can be in:

**`gate-states.ts`**

```typescript
import { Component } from '@angular/core';
import { EpdfDocumentGate } from '@embedpdf/angular/runtime';
import { EpdfRenderLayer } from '@embedpdf/angular/render';
import { EpdfPageTemplate, EpdfStage } from '@embedpdf/angular/stage';
import { PasswordForm } from './password-form';
import { Spinner } from './spinner';

@Component({
  selector: 'app-document-view',
  imports: [EpdfDocumentGate, EpdfStage, EpdfPageTemplate, EpdfRenderLayer, PasswordForm, Spinner],
  template: `
    <epdf-stage *epdfDocumentGate="let document; fallback: opening; locked: locked; error: failed">
      <ng-template epdfPage>
        <epdf-render-layer />
      </ng-template>
    </epdf-stage>

    <ng-template #opening><app-spinner /></ng-template>
    <ng-template #locked let-document><app-password-form [document]="document" /></ng-template>
    <ng-template #failed let-document>
      <p>Couldn't open {{ document.name }}: {{ document.error.message }}</p>
    </ng-template>
  `,
})
export class DocumentView {}
```

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

**`password-form.ts`**

```typescript
import { Component, inject, input, signal } from '@angular/core';
import { EpdfDocuments, type DocumentInfo } from '@embedpdf/angular/runtime';
import { PasswordPrompt } from './password-prompt';

@Component({
  selector: 'app-password-form',
  imports: [PasswordPrompt],
  template: `<app-password-prompt [wrong]="wrong()" (submitted)="submit($event)" />`,
})
export class PasswordForm {
  readonly document = input.required<DocumentInfo>();
  private readonly documents = inject(EpdfDocuments);
  protected readonly wrong = signal(false);

  protected async submit(password: string) {
    try {
      await this.documents.unlock(this.document().id, { password });
    } catch {
      this.wrong.set(true); // it stays locked; ask again
    }
  }
}
```

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

```typescript
import {
  ChangeDetectionStrategy,
  Component,
  inject,
  input,
  linkedSignal,
  signal,
  ViewEncapsulation,
} from '@angular/core';
import { EpdfDocumentGate, EpdfDocuments, provideEmbedPdf } from '@embedpdf/angular/runtime';
import type { DocumentInfo, FailedDocumentInfo, OpenInput } from '@embedpdf/angular/runtime';
import { EpdfPageTemplate, EpdfStage, withStage } from '@embedpdf/angular/stage';
import { EpdfRenderLayer, withRender } from '@embedpdf/angular/render';
import { localEngine } from '@embedpdf/engine';

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

@Component({
  selector: 'demo-password-form',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <div class="panel">
      <h3>{{ document().name }} needs a password</h3>
      @if (wrong()) {
        <p>That password isn’t right. Try again.</p>
      }
      <div class="actions">
        <input
          #field
          class="field"
          type="password"
          aria-label="Password"
          [value]="password()"
          (input)="password.set(field.value)"
        />
        <button type="button" class="button" (click)="unlock()">Unlock</button>
      </div>
    </div>
  `,
})
export class PasswordForm {
  readonly document = input.required<DocumentInfo>();
  private readonly documents = inject(EpdfDocuments);
  protected readonly password = signal('');
  protected readonly wrong = linkedSignal(() => this.document().passwordProvided ?? false);

  protected async unlock() {
    try {
      await this.documents.unlock(this.document().id, { password: this.password() });
    } catch {
      this.wrong.set(true); // it stays locked; ask again
    }
  }
}

@Component({
  selector: 'demo-open-error',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <div class="panel" data-tone="error">
      <h3>Couldn’t open {{ document().name }}</h3>
      <p>{{ document().error.message }}</p>
      <div class="actions">
        <button type="button" class="button" (click)="documents.retry(document().id)">
          Try again
        </button>
        <button type="button" class="button" (click)="documents.close(document().id)">Close</button>
      </div>
    </div>
  `,
})
export class OpenError {
  readonly document = input.required<FailedDocumentInfo>();
  protected readonly documents = inject(EpdfDocuments);
}

@Component({
  selector: 'demo-root',
  imports: [
    EpdfDocumentGate,
    EpdfStage,
    EpdfPageTemplate,
    EpdfRenderLayer,
    PasswordForm,
    OpenError,
  ],
  providers: [
    provideEmbedPdf(
      {
        engine: () => localEngine(),
        initialDocuments: [
          { source: ebook, name: 'ebook.pdf' },
          { source: broken, name: 'broken.pdf', active: true },
        ],
      },
      withStage(),
      withRender(),
    ),
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  styleUrl: './states.css',
  encapsulation: ViewEncapsulation.None,
  template: `
    <div class="tabs" role="tablist">
      @for (document of documents.documents(); track document.id) {
        <button
          type="button"
          role="tab"
          class="tab"
          [attr.aria-selected]="document.id === documents.activeId()"
          (click)="documents.setActive(document.id)"
        >
          <span class="status" [attr.data-status]="document.status"></span>
          {{ document.name }}
        </button>
      }
    </div>

    <epdf-stage
      *epdfDocumentGate="let ready; fallback: opening; locked: locked; error: failed"
      class="stage"
    >
      <ng-template epdfPage>
        <epdf-render-layer />
      </ng-template>
    </epdf-stage>

    <ng-template #opening><div class="panel">Opening…</div></ng-template>
    <ng-template #locked let-document>
      <demo-password-form [document]="document" />
    </ng-template>
    <ng-template #failed let-document>
      <demo-open-error [document]="document" />
    </ng-template>
  `,
})
export class App {
  protected readonly documents = inject(EpdfDocuments);
}
```

**`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, `inject(EpdfDocument)` 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.ts`**

```typescript
import { Component } from '@angular/core';
import { provideEmbedPdf } from '@embedpdf/angular/runtime';
import { EpdfRenderLayer, withRender } from '@embedpdf/angular/render';
import { EpdfPageTemplate, EpdfStage, withStage } from '@embedpdf/angular/stage';
import { engine } from './pdf';

@Component({
  selector: 'app-review-viewer',
  imports: [EpdfStage, EpdfPageTemplate, EpdfRenderLayer],
  providers: [
    provideEmbedPdf(
      {
        engine,
        identity: { userId: 'u_381', displayName: 'Dana Smith' },
        scope: ['doc.open', 'doc.render', 'doc.text.select', 'doc.annotate.read', 'annotations:create:self'],
      },
      withStage(),
      withRender(),
    ),
  ],
  template: `
    <epdf-stage>
      <ng-template epdfPage>
        <epdf-render-layer />
      </ng-template>
    </epdf-stage>
  `,
})
export class ReviewViewer {}
```

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

```typescript
import {
  ChangeDetectionStrategy,
  Component,
  effect,
  inject,
  signal,
  ViewEncapsulation,
} from '@angular/core';
import {
  EpdfDocument,
  EpdfDocumentGate,
  EpdfDocuments,
  EpdfViewer,
  provideEmbedPdf,
} from '@embedpdf/angular/runtime';
import type { OpenInput } from '@embedpdf/angular/runtime';
import { EpdfPageTemplate, EpdfStage, withStage } from '@embedpdf/angular/stage';
import { EpdfRenderLayer, withRender } from '@embedpdf/angular/render';
import { localEngine } from '@embedpdf/engine';

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;

@Component({
  selector: 'demo-root',
  imports: [EpdfDocumentGate, EpdfStage, EpdfPageTemplate, EpdfRenderLayer],
  providers: [
    provideEmbedPdf(
      {
        engine: () => localEngine(),
        identity: dana,
        scope: roles.reader,
        initialDocuments: [{ source: ebook, name: 'ebook.pdf' }],
      },
      withStage(),
      withRender(),
    ),
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  styleUrl: './identity.css',
  encapsulation: ViewEncapsulation.None,
  template: `
    <div class="toolbar">
      <label class="label">
        Dana Smith, as
        <select #picker class="select" [value]="role()" (change)="role.set(asRole(picker.value))">
          <option value="reader">reader</option>
          <option value="editor">editor</option>
        </select>
      </label>
      <!-- Read the document's id too, so the checks are read again when it opens or closes. -->
      @let id = document.id();
      <span class="check" [attr.data-allowed]="!!id && documents.canDownload()"> Download </span>
      <span class="check" [attr.data-allowed]="!!id && documents.canPrint()">Print</span>
    </div>
    <p class="note">
      This document opened for a {{ openedAs() }}.
      @if (openedAs() !== role()) {
        <button type="button" class="button" (click)="openAgain()">
          Open it again as {{ role() }}
        </button>
      }
    </p>

    <epdf-stage *epdfDocumentGate="let ready; fallback: opening" class="stage">
      <ng-template epdfPage>
        <epdf-render-layer />
      </ng-template>
    </epdf-stage>

    <ng-template #opening><p class="loading">Opening…</p></ng-template>
  `,
})
export class App {
  protected readonly documents = inject(EpdfDocuments);
  protected readonly document = inject(EpdfDocument);
  protected readonly role = signal<Role>('reader');
  // The role the open document was opened with: it keeps that one.
  protected readonly openedAs = signal<Role>('reader');

  constructor() {
    // The viewer's scope follows the role; documents opened from now on get it.
    const viewer = inject(EpdfViewer);
    effect(() => viewer.updateSettings({ scope: roles[this.role()] }));
  }

  protected asRole(value: string): Role {
    return value as Role;
  }

  protected async openAgain() {
    const role = this.role();
    await this.documents.close(this.document.id());
    await this.documents.open(ebook, { name: 'ebook.pdf' });
    this.openedAs.set(role);
  }
}
```

**`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
while the app runs with `inject(EpdfViewer).updateSettings({ identity, scope })`, for example when
someone else signs in. 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 `inject(EpdfDocuments)` 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 [`inject(EpdfDocument)`](#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 [`document.pages()`](../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 [`[epdfDocumentScope]`](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

`inject(EpdfDocument)` gives you the document a component talks to: the active one, or the one its
`[epdfDocumentScope]` names. Each field is a signal: read it in a template or a `computed()`, and your view updates when it 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 `[epdfDocumentScope]`                                           |
| `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 [`inject(EpdfDocuments)`](tabs#state).

## Events

**`open-failed.ts`**

```typescript
import { Component, inject } from '@angular/core';
import { toSignal } from '@angular/core/rxjs-interop';
import { map } from 'rxjs';
import { EpdfDocuments } from '@embedpdf/angular/runtime';

@Component({
  selector: 'app-open-error',
  template: `<p role="alert">{{ message() }}</p>`,
})
export class OpenError {
  private readonly documents = inject(EpdfDocuments);

  protected readonly message = toSignal(
    this.documents.openFailed$.pipe(map(({ error }) => `Couldn't open the file: ${error.message}`)),
    { initialValue: '' },
  );
}
```

| Event           | Fires when                                  | Carries                           |
| :-------------- | :------------------------------------------ | :-------------------------------- |
| `opened$`       | A document is open and ready                | `documentId`, `info`              |
| `openFailed$`   | A document couldn't be opened               | `documentId`, `error`             |
| `locked$`       | A document needs a password                 | `documentId`, `passwordProvided`  |
| `closed$`       | A document was closed                       | `documentId`                      |
| `pagesChanged$` | 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/angular/documents/opening)

### `initialDocuments` is read once

Like `engine`, `provideEmbedPdf()` reads `initialDocuments` once, when the viewer starts. To open
another document later, use `documents.open()`, or give the Stage a `[document]` that changes.

### Several documents

A viewer can hold several documents at once, like tabs. See [Several documents](tabs).