---
title: "Outline — Angular"
description: "Show a document's outline (its bookmarks) as a tree, follow its items, mark where the reader is, and let people add, rename, move and delete items."
framework: "Angular"
source: "https://www.cloudpdf.com/docs/headless/angular/documents/outline"
---

# Outline

A document's outline is its table of contents: titled items, nested, each going to a place in the
document. Acrobat calls the items bookmarks. Register `withOutline()` to show it in your UI:

**`outline-list.ts`**

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

@Component({
  selector: 'app-outline-list',
  template: `
    <ul role="tree">
      @for (row of outline.rows(); track row.item.ref.objectNumber) {
        <li
          role="treeitem"
          [attr.aria-level]="row.depth + 1"
          [attr.aria-expanded]="row.hasChildren ? row.expanded : null"
          [attr.aria-current]="
            row.item.ref.objectNumber === outline.current()?.objectNumber ? 'location' : null
          "
          [style.padding-inline-start.px]="row.depth * 16"
        >
          @if (row.hasChildren) {
            <button (click)="outline.toggle(row.item.ref)">{{ row.expanded ? '▾' : '▸' }}</button>
          }
          <button (click)="outline.activate(row.item.ref)">{{ row.item.title }}</button>
        </li>
      }
    </ul>
  `,
})
export class OutlineList {
  protected readonly outline = inject(EpdfOutline);
}
```

What `inject(EpdfOutline)` gives you updates by itself: after your own changes, and on a shared
document, after someone else's. Nothing is read when a document opens: the outline loads the first
time something asks for it, so a document nobody shows the outline of costs nothing.

## Show the outline

`rows` are the rows a tree shows: every item whose parents are all expanded, depth first. Each row
has the `item`, its `depth` (0 at the top level), `hasChildren`, and whether it's `expanded`.
`items` is every item, folded or not, when you'd rather build the tree yourself.

`toggle(ref)` folds or unfolds an item; `expand(ref)`, `collapse(ref)`, `expandAll()` and
`collapseAll()` do one of them. The items the file opens start expanded, and from then on what's
expanded is the reader's: it doesn't change the document.

An item has its `title`, its `color` (`null` when the file sets none, so draw your own text
colour), and whether it's `bold` or `italic`. `status` says whether the outline hasn't been asked
for yet (`'idle'`), is loading, is there (`'ready'`), or couldn't be read. `incomplete` is `true`
when part of the outline couldn't be read, such as a loop in a damaged file; what could be read is
listed.

## Follow an item

`activate(ref)` goes where the item goes, as a click does: a page moves the view, a website opens,
and an item that runs a script runs it, through the [actions plugin](https://www.cloudpdf.com/docs/headless/angular/documents/actions)
when you've registered it. It returns what happened at once, so a website can still open from the
reader's click.

`current` is the item for where the reader is: the last item, in reading order, that goes to a place
at or above the top of the view. Mark its row, and the reader always sees where they are in the
outline:

```ts
const isCurrent = row.item.ref.objectNumber === current?.objectNumber;
```

**`bookmarks.ts`**

```typescript
import { ChangeDetectionStrategy, Component, inject, ViewEncapsulation } from '@angular/core';
import { EpdfDocumentGate, 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 { EpdfOutline, withOutline } from '@embedpdf/angular/outline';
import type { OutlineItem } from '@embedpdf/angular/outline';
import { cloudEngine } from '@cloudpdf/engine';

const welcome: OpenInput = { kind: 'grant', grant: 'shr_gvpJcG1ULUMon19C0D1wODSY' };

// Bookmarks the reader adds: each one goes to the place in view when it's added.
@Component({
  selector: 'demo-root',
  imports: [EpdfDocumentGate, EpdfStage, EpdfPageTemplate, EpdfRenderLayer],
  providers: [
    provideEmbedPdf(
      { engine: () => cloudEngine(), initialDocuments: [{ source: welcome }] },
      withStage(),
      withRender(),
      withOutline(),
    ),
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  styleUrl: './bookmarks.css',
  encapsulation: ViewEncapsulation.None,
  template: `
    <ng-container *epdfDocumentGate="let document; fallback: loading">
      <div class="layout">
        <aside class="bookmarks">
          <header class="bookmarks-header">
            <h3 class="bookmarks-title">Bookmarks</h3>
            <button
              type="button"
              class="button primary"
              [disabled]="!outline.canEdit()"
              (click)="add(stage.currentPageIndex())"
            >
              Add
            </button>
          </header>
          @if (outline.rows().length === 0) {
            <p class="empty">Scroll to a page, then add a bookmark.</p>
          } @else {
            <ul class="list">
              @for (row of outline.rows(); track row.item.ref.objectNumber) {
                <li
                  class="row"
                  [attr.data-current]="isCurrent(row.item) || null"
                  [attr.data-selected]="isSelected(row.item) || null"
                >
                  <button type="button" class="row-title" (click)="follow(row.item)">
                    {{ row.item.title }}
                  </button>
                  <button
                    type="button"
                    class="row-delete"
                    [attr.aria-label]="'Delete ' + row.item.title"
                    [disabled]="!outline.canEdit()"
                    (click)="outline.delete([row.item.ref])"
                  >
                    ×
                  </button>
                </li>
              }
            </ul>
          }
        </aside>

        <epdf-stage #stage="epdfStage" class="stage">
          <ng-template epdfPage>
            <epdf-render-layer />
          </ng-template>
        </epdf-stage>
      </div>
    </ng-container>

    <ng-template #loading><p class="loading">Loading…</p></ng-template>
  `,
})
export class App {
  protected readonly outline = inject(EpdfOutline);

  protected add(pageIndex: number) {
    void this.outline.create({ title: `Page ${pageIndex + 1}` }, { select: true });
  }

  protected follow(item: OutlineItem) {
    this.outline.select([item.ref]);
    this.outline.activate(item.ref);
  }

  protected isCurrent(item: OutlineItem): boolean {
    return item.ref.objectNumber === this.outline.current()?.objectNumber;
  }

  protected isSelected(item: OutlineItem): boolean {
    return item.ref.objectNumber === this.outline.selected()[0]?.objectNumber;
  }
}
```

**`bookmarks.css`**

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

/* The bookmarks beside the pages */
.layout {
  display: grid;
  grid-template-columns: 220px 1fr;
  gap: 14px;
}

.bookmarks {
  display: flex;
  flex-direction: column;
  height: 420px;
  border: 1px solid var(--line);
  border-radius: 14px;
  background: var(--surface);
  box-shadow: 0 1px 2px var(--shadow);
  overflow: hidden;
}

.bookmarks-header {
  display: flex;
  align-items: center;
  justify-content: space-between;
  padding: 10px 10px 10px 14px;
  border-bottom: 1px solid var(--line);
}

.bookmarks-title {
  margin: 0;
  font-size: 13px;
  font-weight: 650;
  color: var(--ink);
}

.empty {
  margin: 0;
  padding: 18px 14px;
  font-size: 12.5px;
  color: var(--muted);
}

/* One row per bookmark: the one being read is marked, the picked one tinted */
.list {
  margin: 0;
  padding: 6px;
  list-style: none;
  overflow-y: auto;
}

.row {
  position: relative;
  display: flex;
  align-items: center;
  border-radius: 8px;
}

.row[data-selected] {
  background: var(--tint);
}

.row[data-current]::before {
  content: '';
  position: absolute;
  inset: 6px auto 6px 0;
  width: 3px;
  border-radius: 3px;
  background: var(--accent);
}

.row-title {
  flex: 1;
  min-width: 0;
  font: inherit;
  font-size: 13px;
  text-align: start;
  color: var(--ink);
  background: none;
  border: 0;
  padding: 7px 10px;
  cursor: pointer;
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

.row-delete {
  font: inherit;
  font-size: 16px;
  line-height: 1;
  color: var(--muted);
  background: none;
  border: 0;
  border-radius: 6px;
  padding: 4px 8px;
  cursor: pointer;
  opacity: 0;
}

.row:hover .row-delete,
.row-delete:focus-visible {
  opacity: 1;
}

.row-delete:hover {
  color: var(--ink);
  background: var(--line);
}

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

.button.primary {
  color: #ffffff;
  background: var(--accent);
  border-color: var(--accent);
}

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

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

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

## Change the outline

`create()` adds an item. Leave out where it goes and it goes to the place in view; leave out its
title and it takes the selected text, or "Untitled" in the viewer's language. It shows at once, and
`select: true` selects it and unfolds the items it sits under, so it's ready to rename:

```ts
await outline.create({ parent: chapter.ref, position: 'end' }, { select: true });
```

`update(ref, changes)` changes the fields you pass: a `title`, a `target`, a `color`, `bold`,
`italic`, or `open` (whether it's expanded when the document opens). `null` removes a target or a
colour. `move(refs, parent, position)` moves items, with the items under them, to their new place,
and `delete(refs)` deletes items with the items under them.

Each of these shows at once, is one step to undo, and resolves once the engine has it. A place is
a neighbour, not a number: `'start'`, `'end'`, `{ before: ref }` or `{ after: ref }` among the
parent's children.

**`nesting.ts`**

```typescript
import {
  ChangeDetectionStrategy,
  Component,
  computed,
  inject,
  signal,
  ViewEncapsulation,
} from '@angular/core';
import { EpdfDocumentGate, provideEmbedPdf } from '@embedpdf/angular/runtime';
import type { OpenInput } from '@embedpdf/angular/runtime';
import { EpdfOutline, withOutline } from '@embedpdf/angular/outline';
import type { OutlineItem, OutlineItemRef } from '@embedpdf/angular/outline';
import { cloudEngine } from '@cloudpdf/engine';

const welcome: OpenInput = { kind: 'grant', grant: 'shr_gvpJcG1ULUMon19C0D1wODSY' };

const same = (left: OutlineItemRef | null, right: OutlineItemRef | null) =>
  left?.objectNumber === right?.objectNumber;

// An outline being built: add items, nest them, fold them, rename and delete them.
@Component({
  selector: 'demo-root',
  imports: [EpdfDocumentGate],
  providers: [
    provideEmbedPdf(
      { engine: () => cloudEngine(), initialDocuments: [{ source: welcome }] },
      withOutline(),
    ),
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  styleUrl: './nesting.css',
  encapsulation: ViewEncapsulation.None,
  template: `
    <ng-container *epdfDocumentGate="let document; fallback: loading">
      <div class="editor">
        <div class="toolbar">
          <input
            #field
            class="field"
            aria-label="Title"
            [value]="title()"
            (input)="title.set(field.value)"
          />
          <button type="button" class="button" [disabled]="!outline.canEdit()" (click)="add(false)">
            Add
          </button>
          <button
            type="button"
            class="button"
            [disabled]="!outline.canEdit() || !item()"
            (click)="add(true)"
          >
            Add inside
          </button>
          <button
            type="button"
            class="button"
            [disabled]="!outline.canEdit() || !previous()"
            (click)="indent()"
          >
            Indent
          </button>
          <button
            type="button"
            class="button"
            [disabled]="!outline.canEdit() || !parent()"
            (click)="outdent()"
          >
            Outdent
          </button>
          <button
            type="button"
            class="button"
            [disabled]="!outline.canEdit() || !item()"
            (click)="rename()"
          >
            Rename
          </button>
          <button
            type="button"
            class="button"
            [disabled]="!outline.canEdit() || !item()"
            (click)="remove()"
          >
            Delete
          </button>
        </div>
        @if (outline.rows().length === 0) {
          <p class="empty">This document has no outline yet. Add an item.</p>
        } @else {
          <ul class="tree" role="tree">
            @for (row of outline.rows(); track row.item.ref.objectNumber) {
              <li
                class="row"
                role="treeitem"
                [attr.aria-level]="row.depth + 1"
                [attr.aria-expanded]="row.hasChildren ? row.expanded : null"
                [attr.aria-selected]="row.item.ref.objectNumber === item()?.ref?.objectNumber"
                [style.padding-inline-start.px]="6 + row.depth * 18"
              >
                <button
                  type="button"
                  class="chevron"
                  [attr.aria-label]="row.expanded ? 'Collapse' : 'Expand'"
                  [disabled]="!row.hasChildren"
                  [attr.data-expanded]="row.expanded || null"
                  (click)="outline.toggle(row.item.ref)"
                ></button>
                <button type="button" class="row-title" (click)="pick(row.item)">
                  {{ row.item.title }}
                </button>
              </li>
            }
          </ul>
        }
      </div>
    </ng-container>

    <ng-template #loading><p class="loading">Loading…</p></ng-template>
  `,
})
export class App {
  protected readonly outline = inject(EpdfOutline);
  protected readonly title = signal('Chapter');
  protected readonly item = computed(() => {
    const [picked] = this.outline.selected();
    return this.outline.items().find((each) => same(each.ref, picked ?? null)) ?? null;
  });
  // The item before the picked one among its parent's children: where an indent puts it.
  protected readonly previous = computed(() => {
    const item = this.item();
    if (!item) return null;
    const siblings = this.outline.items().filter((each) => same(each.parent, item.parent));
    return siblings[siblings.indexOf(item) - 1] ?? null;
  });
  protected readonly parent = computed(() => {
    const item = this.item();
    return this.outline.items().find((each) => same(each.ref, item?.parent ?? null)) ?? null;
  });

  // After the picked item, or at the end.
  protected add(inside: boolean) {
    const item = this.item();
    const title = this.title();
    void this.outline.create(
      inside && item
        ? { title, parent: item.ref }
        : { title, parent: item?.parent ?? null, position: item ? { after: item.ref } : 'end' },
      { select: true },
    );
  }

  protected indent() {
    const item = this.item();
    const previous = this.previous();
    if (!item || !previous) return;
    void this.outline.move([item.ref], previous.ref, 'end');
    this.outline.expand(previous.ref);
  }

  protected outdent() {
    const item = this.item();
    const parent = this.parent();
    if (item && parent) void this.outline.move([item.ref], parent.parent, { after: parent.ref });
  }

  protected rename() {
    const item = this.item();
    if (item) void this.outline.update(item.ref, { title: this.title() });
  }

  protected remove() {
    const item = this.item();
    if (item) void this.outline.delete([item.ref]);
  }

  protected pick(item: OutlineItem) {
    this.outline.select([item.ref]);
    this.title.set(item.title);
  }
}
```

**`nesting.css`**

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

/* The title to add or rename with, and what to do with the picked item */
.toolbar {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 8px;
  margin-bottom: 14px;
}

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

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

.button {
  font: inherit;
  font-size: 12px;
  font-weight: 600;
  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,
.chevron:focus-visible,
.row-title:focus-visible {
  outline: 2px solid var(--focus);
  outline-offset: 2px;
}

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

/* The tree: each level indented, a parent with a chevron that folds it */
.tree {
  margin: 0;
  padding: 6px;
  list-style: none;
  min-height: 220px;
  border: 1px solid var(--line);
  border-radius: 14px;
  background: var(--surface);
  box-shadow: 0 1px 2px var(--shadow);
}

.row {
  display: flex;
  align-items: center;
  gap: 2px;
  border-radius: 8px;
}

.row[aria-selected='true'] {
  background: var(--tint);
}

.chevron {
  display: grid;
  place-items: center;
  width: 22px;
  height: 22px;
  color: var(--muted);
  background: none;
  border: 0;
  border-radius: 6px;
  cursor: pointer;
  transition: transform 0.15s ease;
}

/* Drawn rather than typed, so it's the same size in every font: a right-pointing chevron */
.chevron::before {
  content: '';
  width: 6px;
  height: 6px;
  border-right: 1.5px solid currentColor;
  border-bottom: 1.5px solid currentColor;
  transform: translateX(-1px) rotate(-45deg);
}

.chevron:disabled {
  visibility: hidden;
}

.chevron[data-expanded] {
  transform: rotate(90deg);
}

.row-title {
  flex: 1;
  min-width: 0;
  font: inherit;
  font-size: 13px;
  text-align: start;
  color: var(--ink);
  background: none;
  border: 0;
  padding: 7px 8px;
  cursor: pointer;
}

.empty {
  margin: 0;
  padding: 18px;
  font-size: 12.5px;
  color: var(--muted);
  border: 1px dashed var(--line-strong);
  border-radius: 14px;
}

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

## Select items

`select(refs)` makes items the selection, and `selected` lists them. The selection is the
reader's, like what's expanded: show it, and act on it with your own buttons.

```ts
outline.select([row.item.ref]);
await outline.delete(selected);
```

## Methods

Everything `inject(EpdfOutline)` gives you.

| Method                         | What it does                                                                                               |
| :----------------------------- | :--------------------------------------------------------------------------------------------------------- |
| `get(ref)`                     | One item, or `null`.                                                                                       |
| `getChildren(parent)`          | An item's children in order, or the top level's for `null`.                                                |
| `isExpanded(ref)`              | Whether an item's children show. [Show the outline](#show-the-outline)                                     |
| `toggle(ref)`                  | Folds an expanded item, unfolds a folded one.                                                              |
| `expand(ref)`, `collapse(ref)` | Unfolds or folds one item.                                                                                 |
| `expandAll()`, `collapseAll()` | Unfolds or folds every item.                                                                               |
| `reveal(ref)`                  | Unfolds every item `ref` sits under, so its row shows.                                                     |
| `select(refs)`                 | Makes these items the selection; `[]` clears it. [Select items](#select-items)                             |
| `activate(ref)`                | Goes where the item goes, as a click does, and returns what happened. [Follow an item](#follow-an-item)    |
| `getCurrentViewTarget()`       | Where the view is, as a target: the page at its top and the spot at its top-left. What a new item goes to. |
| `create(item, options)`        | Adds an item; `select: true` selects it. Resolves `{ item }`. [Change the outline](#change-the-outline)    |
| `update(ref, changes)`         | Changes the fields you pass; `null` removes a target or a colour. Resolves `{ item }`.                     |
| `move(refs, parent, position)` | Moves items, with the items under them, to their new place.                                                |
| `delete(refs)`                 | Deletes items with the items under them, as one change.                                                    |
| `ensureLoaded()`               | Reads the outline from the file, unless it's loaded or loading. Resolves once it's there.                  |
| `refresh()`                    | Reads the outline again. Rarely needed: it stays up to date by itself.                                     |

Every method that returns a promise also takes a `signal` in its options, to cancel it.

## State

Every value is a signal on `inject(EpdfOutline)`: read it in a template or a `computed()`, and your view updates when it changes. The method in the last column reads the same value once.

| Field          | What it is                                                                                    | Read once          |
| :------------- | :-------------------------------------------------------------------------------------------- | :----------------- |
| `items()`      | Every item, depth first, with your changes shown before the engine answers                    | `list()`           |
| `rows()`       | The rows a tree shows: `item`, `depth`, `hasChildren`, `expanded`                             | `listRows()`       |
| `current()`    | The item for where the reader is, or `null`                                                   | `getCurrentItem()` |
| `selected()`   | The selected items, in the order they were selected                                           | `getSelected()`    |
| `status()`     | `'idle'` until something asks for it, then `'loading'`, `'ready'`, `'forbidden'` or `'error'` | `getStatus()`      |
| `incomplete()` | Part of the outline couldn't be read                                                          | `isIncomplete()`   |
| `canEdit()`    | Whether changing the outline is allowed                                                       | `canEdit()`        |

## Events

**`outline-changed.ts`**

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

@Component({
  selector: 'app-outline-notice',
  template: `<p role="status">{{ notice() }}</p>`,
})
export class OutlineNotice {
  private readonly outline = inject(EpdfOutline);

  protected readonly notice = toSignal(
    this.outline.changed$.pipe(
      filter(({ origin }) => origin.kind === 'remote'),
      map(({ type, items }) => `Someone ${type} ${items.length} bookmark(s)`),
    ),
    { initialValue: '' },
  );
}
```

| Event       | Fires when                                                                                                                   | Carries                   |
| :---------- | :--------------------------------------------------------------------------------------------------------------------------- | :------------------------ |
| `changed$`  | Items were created, updated, moved, deleted or restored, by you or by someone else                                           | `type`, `items`, `origin` |
| `resynced$` | The outline was read from the file: the first time it's asked for, after `refresh()`, or to catch up after a lost connection | `outline`                 |

`type` is `'created'`, `'updated'`, `'moved'`, `'deleted'` or `'restored'`, and `items` names the
items it touched; for a delete, the item first, then the items under it.

## Permissions

| Permission           | What it allows                              | Check               |
| :------------------- | :------------------------------------------ | :------------------ |
| `doc.open`           | Reading the outline                         | none: it opened     |
| `doc.outline.modify` | Adding, changing, moving and deleting items | `outline.canEdit()` |

## Good to know

### Expanded, and open

What's expanded is the reader's view, not the document: folding an item doesn't change the file.
An item's `open` is the file's own setting, whether its children show when the document opens, and
the outline starts from it. Change it with `update(ref, { open })`.

### Pages that are gone

Deleting a page doesn't delete the items that go to it: their target reads `unsupported`, and
`activate()` reports it rather than going anywhere. See
[Outline](https://www.cloudpdf.com/docs/engine/documents/outline#pages-that-are-gone).

### The ready-made viewer

The viewer's Outline panel is built on this plugin. See
[Panels](https://www.cloudpdf.com/docs/viewer/angular/customize/panels).