EmbedPDF

Tools & defaults

A tool says what a click or a drag on the page creates: the kind of annotation, its default colors and sizes, the cursor, and whether a preview follows the pointer. Change the built-in tools, or add your own, with the tools setting of withAnnotation():

withAnnotation({
  tools: [
    { id: 'ink', defaults: { color: '#1e90ff', strokeWidth: 3 } },
    {
      id: 'arrow',
      extends: 'line',
      defaults: { lineEndings: { start: 'none', end: 'closed-arrow' } },
    },
  ],
});

The first entry changes the built-in ink tool. The second adds an arrow tool: a line with an arrowhead. Activate a tool with interaction.activateTool('arrow'), as on the overview.

Change the default color, width and font#

A tool’s defaults are the fields every annotation it draws starts with. They’re the same fields the annotation has, so the engine’s page for each kind lists what you can set:

withAnnotation({
  tools: [
    { id: 'square', defaults: { color: '#dc143c', strokeWidth: 2, interiorColor: '#ffe4e1' } },
    { id: 'highlight', defaults: { color: '#90ee90', opacity: 0.6 } },
    { id: 'free-text', defaults: { fontFamily: 'helvetica', fontSize: 16, fontColor: '#1e1e1e' } },
    { id: 'note', defaults: { icon: 'help', color: '#ffd700' } },
  ],
});

Defaults can be any field except where the annotation goes (box, points, rect), since that comes from the drawing. Flags are fields too: { id: 'note', defaults: { locked: true } } makes every new note locked.

A field the tool’s kind doesn’t have (a fontSize on a square) stops the app at startup with an error that names the tool and the field.

Make your own tool#

extends starts from a tool and changes what you name. The new tool keeps everything else: its kind, cursor, preview and behavior:

withAnnotation({
  tools: [
    { id: 'red-pen', extends: 'ink', defaults: { color: '#ff0000', strokeWidth: 2 } },
    { id: 'marker', extends: 'ink-highlight', defaults: { color: '#ffa500' } },
    { id: 'todo', extends: 'note', defaults: { icon: 'key', contents: 'TODO' } },
    {
      id: 'docs-link',
      extends: 'link',
      defaults: { target: { kind: 'uri', uri: 'https://example.com/docs' } },
    },
  ],
});

Give a tool a label and an icon for your toolbar in meta. The plugin keeps it and never reads it:

withAnnotation({
  tools: [{ id: 'red-pen', extends: 'ink', meta: { label: 'Red pen', icon: 'pen' } }],
});

annotation.tools.list() returns every tool, so a toolbar can build itself from it.

Loading live preview…

import {
  ChangeDetectionStrategy,
  Component,
  effect,
  inject,
  untracked,
  ViewEncapsulation,
} from '@angular/core';
import { EpdfDocument, 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 { EpdfInteraction, withInteraction } from '@embedpdf/angular/interaction';
import { EpdfAnnotation, EpdfAnnotationLayer, withAnnotation } from '@embedpdf/angular/annotation';
import type { AnnotationTool } from '@embedpdf/angular/annotation';
import { localEngine } from '@embedpdf/engine';

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

// A toolbar that builds itself from the tools: every tool with a label gets a button.
@Component({
  selector: 'demo-toolbar',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <div class="toolbar">
      <div class="segmented" role="group" aria-label="Tool">
        <button
          type="button"
          [attr.aria-pressed]="interaction.activeToolId() === 'pointer'"
          (click)="interaction.activateTool('pointer')"
        >
          Select
        </button>
        @for (tool of labelled; track tool.id) {
          <button
            type="button"
            [attr.aria-pressed]="interaction.activeToolId() === tool.id"
            (click)="interaction.activateTool(tool.id)"
          >
            {{ label(tool) }}
          </button>
        }
      </div>
    </div>
  `,
})
export class Toolbar {
  private readonly annotation = inject(EpdfAnnotation);
  protected readonly interaction = inject(EpdfInteraction);
  private readonly document = inject(EpdfDocument);
  protected readonly labelled = this.annotation.tools
    .list()
    .filter((tool) => typeof tool.meta?.label === 'string');
  private added = false;

  constructor() {
    // On load: an arrow drawn with the arrow tool's defaults, and the arrow tool active.
    effect(() => {
      const cover = this.document.pages()[0]?.ref;
      if (this.annotation.status() !== 'ready' || !cover || this.added) return;
      this.added = true;
      untracked(() => {
        void this.annotation.create(
          cover,
          { subtype: 'line', linePoints: { start: { x: 520, y: 120 }, end: { x: 470, y: 230 } } },
          undefined,
          { tool: 'arrow' },
        );
        this.interaction.activateTool('arrow');
      });
    });
  }

  protected label(tool: AnnotationTool) {
    return String(tool.meta?.label);
  }
}

@Component({
  selector: 'demo-root',
  imports: [
    EpdfDocumentGate,
    EpdfStage,
    EpdfPageTemplate,
    EpdfRenderLayer,
    EpdfAnnotationLayer,
    Toolbar,
  ],
  providers: [
    provideEmbedPdf(
      { engine: () => localEngine(), initialDocuments: [{ source: ebook }] },
      withStage(),
      withRender(),
      withInteraction(),
      // A blue pen, an arrow, and three tools of your own. `meta` is yours: the toolbar reads its label.
      withAnnotation({
        tools: [
          {
            id: 'ink',
            defaults: { color: '#1e90ff', strokeWidth: 3 },
            meta: { label: 'Blue pen' },
          },
          {
            id: 'arrow',
            extends: 'line',
            defaults: { lineEndings: { start: 'none', end: 'closed-arrow' } },
            meta: { label: 'Arrow' },
          },
          {
            id: 'red-pen',
            extends: 'ink',
            defaults: { color: '#ff0000', strokeWidth: 2 },
            meta: { label: 'Red pen' },
          },
          {
            id: 'marker',
            extends: 'ink-highlight',
            defaults: { color: '#ffa500' },
            meta: { label: 'Marker' },
          },
          {
            id: 'todo',
            extends: 'note',
            defaults: { icon: 'key', contents: 'TODO' },
            meta: { label: 'To do' },
          },
        ],
      }),
    ),
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  styleUrl: './custom-tools.css',
  encapsulation: ViewEncapsulation.None,
  template: `
    <ng-container *epdfDocumentGate="let document; fallback: loading">
      <demo-toolbar />
      <epdf-stage class="stage">
        <ng-template epdfPage>
          <epdf-render-layer />
          <epdf-annotation-layer />
        </ng-template>
      </epdf-stage>
    </ng-container>

    <ng-template #loading><p class="loading">Loading…</p></ng-template>
  `,
})
export class App {}

Try it: every button but Select comes from a tool’s meta. Draw with Red pen, then place a To do note.

Tools can also be added while the app runs. register() returns a function that removes the tool again:

const remove = annotation.tools.register({
  id: 'green-pen',
  extends: 'ink',
  defaults: { color: '#00a000' },
});

Let people change the defaults#

A color picker or a width slider in your toolbar changes a tool’s defaults for the drawings that follow:

ink-color.ts
import { Component, inject } from '@angular/core';
import { EpdfAnnotation } from '@embedpdf/angular/annotation';

@Component({
  selector: 'app-ink-color',
  template: `
    <input
      #picker
      type="color"
      [value]="defaults().color"
      (input)="annotation.tools.updateDefaults('ink', { color: picker.value })"
    />
  `,
})
export class InkColor {
  protected readonly annotation = inject(EpdfAnnotation);
  protected readonly defaults = this.annotation.tools.defaultsOf('ink');
}

annotation.tools.defaultsOf() updates when the defaults change, so the picker always shows the current color. To build a whole style panel for any tool, ask for its fields; they come in the same shape as a style panel for the selection:

const { properties, values } = annotation.tools.getProperties('ink'); // color, opacity, strokeWidth, …

Defaults belong to the person drawing: they’re kept in this viewer and never shared with others on the same document.

Remember them#

To keep a person’s choices for next time, save them when they change:

remember.ts
import { Component, inject } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { EpdfAnnotation } from '@embedpdf/angular/annotation';

@Component({
  selector: 'app-remember-defaults',
  template: '',
})
export class RememberDefaults {
  constructor() {
    inject(EpdfAnnotation)
      .tools.defaultsChanged$.pipe(takeUntilDestroyed())
      .subscribe(({ toolId, defaults }) => {
        localStorage.setItem(`tool:${toolId}`, JSON.stringify(defaults));
      });
  }
}

Then pass them back at startup:

withAnnotation({
  tools: ['ink', 'highlight'].map((id) => ({
    id,
    defaults: JSON.parse(localStorage.getItem(`tool:${id}`) ?? '{}'),
  })),
});

Loading live preview…

import {
  ChangeDetectionStrategy,
  Component,
  effect,
  inject,
  untracked,
  ViewEncapsulation,
} from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { EpdfDocument, 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 { EpdfInteraction, withInteraction } from '@embedpdf/angular/interaction';
import { EpdfAnnotation, EpdfAnnotationLayer, withAnnotation } from '@embedpdf/angular/annotation';
import { localEngine } from '@embedpdf/engine';

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

const COLORS = ['#e5484d', '#1e90ff', '#30a46c', '#1a2748'];

// The pen's color and width, for the strokes that follow.
@Component({
  selector: 'demo-pen-style',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <div class="toolbar">
      <div class="swatches" role="group" aria-label="Pen color">
        @for (color of colors; track color) {
          <button
            type="button"
            class="swatch"
            [attr.aria-label]="color"
            [attr.aria-pressed]="defaults().color === color"
            [style.background]="color"
            (click)="annotation.tools.updateDefaults('ink', { color })"
          ></button>
        }
      </div>
      <input
        #picker
        type="color"
        class="color"
        aria-label="Any color"
        [value]="defaults().color ?? '#000000'"
        (input)="annotation.tools.updateDefaults('ink', { color: picker.value })"
      />
      <label class="range">
        Width
        <input
          #width
          type="range"
          min="1"
          max="12"
          [value]="defaults().strokeWidth ?? 1"
          (input)="annotation.tools.updateDefaults('ink', { strokeWidth: width.valueAsNumber })"
        />
        <output class="readout">{{ defaults().strokeWidth }} pt</output>
      </label>
    </div>
  `,
})
export class PenStyle {
  protected readonly colors = COLORS;
  protected readonly annotation = inject(EpdfAnnotation);
  protected readonly defaults = this.annotation.tools.defaultsOf('ink');
}

// Every change is kept for next time.
@Component({
  selector: 'demo-remember-defaults',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: '',
})
export class RememberDefaults {
  constructor() {
    inject(EpdfAnnotation)
      .tools.defaultsChanged$.pipe(takeUntilDestroyed())
      .subscribe(({ toolId, defaults }) => {
        localStorage.setItem(`tool:${toolId}`, JSON.stringify(defaults));
      });
  }
}

// On load: the pen is active, with a stroke drawn in its current style.
@Component({
  selector: 'demo-start-with-the-pen',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: '',
})
export class StartWithThePen {
  private readonly annotation = inject(EpdfAnnotation);
  private readonly interaction = inject(EpdfInteraction);
  private readonly document = inject(EpdfDocument);
  private added = false;

  constructor() {
    effect(() => {
      const cover = this.document.pages()[0]?.ref;
      if (this.annotation.status() !== 'ready' || !cover || this.added) return;
      this.added = true;
      untracked(() => {
        const wave = Array.from({ length: 24 }, (_, i) => ({
          x: 300 + i * 10,
          y: 540 + Math.sin(i / 2) * 14,
        }));
        void this.annotation.create(cover, { subtype: 'ink', inkList: [wave] }, undefined, {
          tool: 'ink',
        });
        this.interaction.activateTool('ink');
      });
    });
  }
}

@Component({
  selector: 'demo-root',
  imports: [
    EpdfDocumentGate,
    EpdfStage,
    EpdfPageTemplate,
    EpdfRenderLayer,
    EpdfAnnotationLayer,
    StartWithThePen,
    RememberDefaults,
    PenStyle,
  ],
  providers: [
    provideEmbedPdf(
      { engine: () => localEngine(), initialDocuments: [{ source: ebook }] },
      withStage(),
      withRender(),
      withInteraction(),
      // The pen starts with what the reader picked last time: see RememberDefaults above.
      withAnnotation({
        tools: [{ id: 'ink', defaults: JSON.parse(localStorage.getItem('tool:ink') ?? '{}') }],
      }),
    ),
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  styleUrl: './tool-defaults.css',
  encapsulation: ViewEncapsulation.None,
  template: `
    <ng-container *epdfDocumentGate="let document; fallback: loading">
      <demo-start-with-the-pen />
      <demo-remember-defaults />
      <demo-pen-style />
      <epdf-stage class="stage">
        <ng-template epdfPage>
          <epdf-render-layer />
          <epdf-annotation-layer />
        </ng-template>
      </epdf-stage>
    </ng-container>

    <ng-template #loading><p class="loading">Loading…</p></ng-template>
  `,
})
export class App {}

Try it: pick a color and a width, and draw. Reload the page: the pen still has them.

What happens after drawing#

By default the new annotation is selected, so its handles and your menu appear at once, and the tool stays active, so people can draw another. Change it for every tool, or for one:

withAnnotation({
  afterCreate: { select: false, tool: 'stay' }, // every tool: keep drawing, don't select
  tools: [
    { id: 'stamp', afterCreate: { select: true, tool: 'default' } }, // one stamp, then back
  ],
});
SettingWhat it doesDefault
selectSelect the new annotation.true
tool'stay' keeps the tool active. 'default' goes back to the default tool, usually pointer.'stay'
editTextFor text boxes: start typing in the new box right away.true

A tool’s own afterCreate wins over the one for every tool.

The setting can change while the app runs. A “keep tool” button in your toolbar is one call:

annotation.updateSettings({ afterCreate: { tool: keepTool ? 'stay' : 'default' } });

Loading live preview…

import {
  ChangeDetectionStrategy,
  Component,
  computed,
  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 { EpdfInteraction, withInteraction } from '@embedpdf/angular/interaction';
import { EpdfAnnotation, EpdfAnnotationLayer, withAnnotation } from '@embedpdf/angular/annotation';
import { localEngine } from '@embedpdf/engine';

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

@Component({
  selector: 'demo-after-drawing',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <div class="toolbar">
      <button
        type="button"
        class="button"
        [attr.aria-pressed]="interaction.activeToolId() === 'square'"
        (click)="interaction.activateTool('square')"
      >
        Rectangle
      </button>
      <label class="check">
        <input
          #select
          type="checkbox"
          [checked]="afterCreate().select"
          (change)="annotation.updateSettings({ afterCreate: { select: select.checked } })"
        />
        Select it
      </label>
      <label class="check">
        <input
          #stay
          type="checkbox"
          [checked]="afterCreate().tool === 'stay'"
          (change)="
            annotation.updateSettings({ afterCreate: { tool: stay.checked ? 'stay' : 'default' } })
          "
        />
        Keep the tool
      </label>
      <button type="button" class="button" (click)="annotation.resetSettings()">Reset</button>
      <span class="spacer"></span>
      <output class="readout">
        {{ interaction.activeToolId() === 'square' ? 'Drawing' : 'Selecting' }}
      </output>
    </div>
  `,
})
export class AfterDrawing {
  protected readonly annotation = inject(EpdfAnnotation);
  protected readonly interaction = inject(EpdfInteraction);
  protected readonly afterCreate = computed(() => this.annotation.settings().afterCreate);

  constructor() {
    // The rectangle tool is active on load.
    this.interaction.activateTool('square');
  }
}

@Component({
  selector: 'demo-root',
  imports: [
    EpdfDocumentGate,
    EpdfStage,
    EpdfPageTemplate,
    EpdfRenderLayer,
    EpdfAnnotationLayer,
    AfterDrawing,
  ],
  providers: [
    provideEmbedPdf(
      { engine: () => localEngine(), initialDocuments: [{ source: ebook }] },
      withStage(),
      withRender(),
      withInteraction(),
      withAnnotation(),
    ),
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  styleUrl: './after-create.css',
  encapsulation: ViewEncapsulation.None,
  template: `
    <ng-container *epdfDocumentGate="let document; fallback: loading">
      <demo-after-drawing />
      <epdf-stage class="stage">
        <ng-template epdfPage>
          <epdf-render-layer />
          <epdf-annotation-layer />
        </ng-template>
      </epdf-stage>
    </ng-container>

    <ng-template #loading><p class="loading">Loading…</p></ng-template>
  `,
})
export class App {}

Try it: draw a rectangle, then turn off Keep the tool and draw another: the tool goes back to selecting.

Annotations your code creates are never selected unless you ask for it; see Create an annotation.

Click or drag#

Most drawing tools also work with a single click: it places an annotation of a default size where you click. clickCreate sets that size, or turns it off:

withAnnotation({
  tools: [
    { id: 'square', clickCreate: { width: 120, height: 80 } },
    { id: 'line', clickCreate: { length: 100 } },
    { id: 'circle', clickCreate: false }, // drag only
  ],
});
ToolA click makes
square, circle80 × 60 points, centered on the click
line80 points long, pointing right, centered on the click
free-text180 × 40 points, its top-left at the click
note, attachmentA 20 × 20 icon
stampThe stamp, 150 points wide, centered on the click

anchor says which part of it lands on the click. A box takes 'center' (the default) or 'top-left'; a line takes 'center' (the default), 'start' or 'end'. A line’s rotation turns it clockwise from pointing right, in degrees. An arrow whose tip lands where you click, pointing down:

withAnnotation({
  tools: [{ id: 'arrow', clickCreate: { length: 80, rotation: 90, anchor: 'end' } }],
});

Loading live preview…

import {
  ChangeDetectionStrategy,
  Component,
  computed,
  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 { EpdfInteraction, withInteraction } from '@embedpdf/angular/interaction';
import { EpdfAnnotationLayer, withAnnotation } from '@embedpdf/angular/annotation';
import { localEngine } from '@embedpdf/engine';

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

const TOOLS = [
  { id: 'square', label: 'Rectangle', hint: 'A click makes 120 × 80 points' },
  { id: 'arrow', label: 'Arrow', hint: 'A click points an arrow down at it' },
  { id: 'circle', label: 'Circle', hint: 'Drag only: a click does nothing' },
];

@Component({
  selector: 'demo-toolbar',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <div class="toolbar">
      <div class="segmented" role="group" aria-label="Tool">
        @for (tool of tools; track tool.id) {
          <button
            type="button"
            [attr.aria-pressed]="interaction.activeToolId() === tool.id"
            (click)="interaction.activateTool(tool.id)"
          >
            {{ tool.label }}
          </button>
        }
      </div>
      <p class="hint">{{ active()?.hint ?? 'Pick a tool, then click the page' }}</p>
    </div>
  `,
})
export class Toolbar {
  protected readonly tools = TOOLS;
  protected readonly interaction = inject(EpdfInteraction);
  protected readonly active = computed(() =>
    TOOLS.find((tool) => tool.id === this.interaction.activeToolId()),
  );

  constructor() {
    // The rectangle tool is active on load: click the page.
    this.interaction.activateTool('square');
  }
}

@Component({
  selector: 'demo-root',
  imports: [
    EpdfDocumentGate,
    EpdfStage,
    EpdfPageTemplate,
    EpdfRenderLayer,
    EpdfAnnotationLayer,
    Toolbar,
  ],
  providers: [
    provideEmbedPdf(
      { engine: () => localEngine(), initialDocuments: [{ source: ebook }] },
      withStage(),
      withRender(),
      withInteraction(),
      // What one click makes: a 120 × 80 rectangle, an arrow pointing down at the click, and no circle.
      withAnnotation({
        tools: [
          { id: 'square', clickCreate: { width: 120, height: 80 } },
          {
            id: 'arrow',
            extends: 'line',
            defaults: { lineEndings: { start: 'none', end: 'closed-arrow' } },
            clickCreate: { length: 80, rotation: 90, anchor: 'end' },
          },
          { id: 'circle', clickCreate: false }, // drag only
        ],
      }),
    ),
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  styleUrl: './click-create.css',
  encapsulation: ViewEncapsulation.None,
  template: `
    <ng-container *epdfDocumentGate="let document; fallback: loading">
      <demo-toolbar />
      <epdf-stage class="stage">
        <ng-template epdfPage>
          <epdf-render-layer />
          <epdf-annotation-layer />
        </ng-template>
      </epdf-stage>
    </ng-container>

    <ng-template #loading><p class="loading">Loading…</p></ng-template>
  `,
})
export class App {}

Try it: click the page with each tool. The arrow’s tip lands where you click.

What a click makes always stays on the page: near an edge, it’s moved inside.

The cursor#

While a tool is active, the pointer shows the tool’s cursor. Over an annotation the viewer switches to a move or resize cursor by itself, and over text to a text cursor, so people always see what a click will do. You choose the cursor for the rest of the page. There are three steps, from simple to fully yours.

A standard cursor. Any CSS cursor name:

withAnnotation({ tools: [{ id: 'square', cursor: 'cell' }] });

An image. svgCursor(), from @embedpdf/angular/interaction, turns an SVG into a cursor. The SVG needs a width and a height, and hotspot is the point in it that clicks:

withAnnotation({
  tools: [{ id: 'ink', cursor: svgCursor({ svg: penIcon, hotspot: { x: 2, y: 22 } }) }],
});

An image that follows the defaults. interaction.overrideCursor() sets a tool’s cursor from a component, so it can change with the tool’s color:

ink-cursor.ts
import { Component, inject } from '@angular/core';
import { EpdfAnnotation } from '@embedpdf/angular/annotation';
import { EpdfInteraction } from '@embedpdf/angular/interaction';

import { penIcon } from './icons';

@Component({
  selector: 'app-ink-cursor',
  template: '',
})
export class InkCursor {
  private readonly defaults = inject(EpdfAnnotation).tools.defaultsOf('ink');

  constructor() {
    // Follows the color, and gives the tool its own cursor back when this component goes
    inject(EpdfInteraction).overrideCursor(() => ({
      toolId: 'ink',
      cursors: { crosshair: { svg: penIcon(this.defaults().color), hotspot: { x: 2, y: 22 } } },
    }));
  }
}

cursors replaces cursors by name: crosshair is the ink tool’s own cursor. Name text too to replace the text cursor a markup tool shows over text. The cursor goes back to the tool’s own when the component is removed.

Loading live preview…

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 { EpdfInteraction, withInteraction } from '@embedpdf/angular/interaction';
import { EpdfAnnotation, EpdfAnnotationLayer, withAnnotation } from '@embedpdf/angular/annotation';
import { localEngine } from '@embedpdf/engine';

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

// A pen, 24 × 24, in a color: its tip is the bottom-left corner.
const penIcon = (color: string) =>
  `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">` +
  `<path d="M3 21l1.5-5.5L16 4l4 4L8.5 19.5z" fill="${color}" stroke="#ffffff" stroke-width="1.5" stroke-linejoin="round"/>` +
  `</svg>`;

// The pen cursor follows the pen's color: the spec is read again when the color changes.
@Component({
  selector: 'demo-ink-cursor',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: '',
})
export class InkCursor {
  constructor() {
    const defaults = inject(EpdfAnnotation).tools.defaultsOf('ink');
    inject(EpdfInteraction).overrideCursor(() => ({
      toolId: 'ink',
      cursors: {
        crosshair: { svg: penIcon(defaults().color ?? '#000000'), hotspot: { x: 2, y: 22 } },
      },
    }));
  }
}

const COLORS = ['#e5484d', '#1e90ff', '#30a46c', '#1a2748'];

@Component({
  selector: 'demo-toolbar',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <div class="toolbar">
      <button
        type="button"
        class="button"
        [attr.aria-pressed]="interaction.activeToolId() === 'ink'"
        (click)="interaction.activateTool('ink')"
      >
        Pen
      </button>
      <div class="swatches" role="group" aria-label="Pen color">
        @for (swatch of colors; track swatch) {
          <button
            type="button"
            class="swatch"
            [attr.aria-label]="swatch"
            [attr.aria-pressed]="defaults().color === swatch"
            [style.background]="swatch"
            (click)="pick(swatch)"
          ></button>
        }
      </div>
      <button
        type="button"
        class="button"
        [attr.aria-pressed]="interaction.activeToolId() === 'square'"
        (click)="interaction.activateTool('square')"
      >
        Rectangle
      </button>
    </div>
  `,
})
export class Toolbar {
  protected readonly colors = COLORS;
  private readonly annotation = inject(EpdfAnnotation);
  protected readonly interaction = inject(EpdfInteraction);
  protected readonly defaults = this.annotation.tools.defaultsOf('ink');

  constructor() {
    // The pen is active on load: move the pointer over the page.
    this.interaction.activateTool('ink');
  }

  protected pick(swatch: string) {
    this.annotation.tools.updateDefaults('ink', { color: swatch });
    this.interaction.activateTool('ink');
  }
}

@Component({
  selector: 'demo-root',
  imports: [
    EpdfDocumentGate,
    EpdfStage,
    EpdfPageTemplate,
    EpdfRenderLayer,
    EpdfAnnotationLayer,
    InkCursor,
    Toolbar,
  ],
  providers: [
    provideEmbedPdf(
      { engine: () => localEngine(), initialDocuments: [{ source: ebook }] },
      withStage(),
      withRender(),
      withInteraction(),
      // A standard cursor for the rectangle tool: any CSS cursor name.
      withAnnotation({ tools: [{ id: 'square', cursor: 'cell' }] }),
    ),
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  styleUrl: './cursor.css',
  encapsulation: ViewEncapsulation.None,
  template: `
    <ng-container *epdfDocumentGate="let document; fallback: loading">
      <demo-ink-cursor />
      <demo-toolbar />
      <epdf-stage class="stage">
        <ng-template epdfPage>
          <epdf-render-layer />
          <epdf-annotation-layer />
        </ng-template>
      </epdf-stage>
    </ng-container>

    <ng-template #loading><p class="loading">Loading…</p></ng-template>
  `,
})
export class App {}

Try it: move the pointer over the page, then pick another color. Rectangle shows the standard cell cursor.

Show a preview before placing#

A preview (a ghost) is a see-through copy of what a click would place, following the pointer. It shows exactly where the annotation will land and how big it will be:

withAnnotation({
  tools: [
    { id: 'square', ghost: true },
    { id: 'note', ghost: { opacity: 0.3 } },
    { id: 'todo', extends: 'note', ghost: false },
  ],
});

The preview is the annotation the click will make, drawn with the tool’s current defaults: its color, its width, an arrow’s head, a form field’s border and background. Change a default and the preview changes with it. It’s half see-through unless you set opacity; --epdf-ghost-opacity sets it from CSS for every tool (see Colors & theming).

Loading live preview…

import {
  ChangeDetectionStrategy,
  Component,
  computed,
  inject,
  model,
  signal,
  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 { EpdfInteraction, withInteraction } from '@embedpdf/angular/interaction';
import { EpdfAnnotationLayer, withAnnotation } from '@embedpdf/angular/annotation';
import { localEngine } from '@embedpdf/engine';

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

const TOOLS = [
  { id: 'note', label: 'Note' },
  { id: 'square', label: 'Rectangle' },
];

@Component({
  selector: 'demo-toolbar',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <div class="toolbar">
      <div class="segmented" role="group" aria-label="Tool">
        @for (tool of tools; track tool.id) {
          <button
            type="button"
            [attr.aria-pressed]="interaction.activeToolId() === tool.id"
            (click)="interaction.activateTool(tool.id)"
          >
            {{ tool.label }}
          </button>
        }
      </div>
      <label class="range">
        From CSS
        <input
          #slider
          type="range"
          min="0.1"
          max="0.9"
          step="0.1"
          [value]="opacity() ?? 0.5"
          (input)="opacity.set(+slider.value)"
        />
        <output class="readout">{{ readout() }}</output>
      </label>
      <button
        type="button"
        class="button"
        [disabled]="opacity() === null"
        (click)="opacity.set(null)"
      >
        Reset
      </button>
    </div>
  `,
})
export class Toolbar {
  /** The ghost opacity from CSS, or `null` for each tool's own. */
  readonly opacity = model.required<number | null>();

  protected readonly interaction = inject(EpdfInteraction);
  protected readonly tools = TOOLS;
  protected readonly readout = computed(() => {
    const opacity = this.opacity();
    return opacity === null ? "each tool's own" : `${Math.round(opacity * 100)}%`;
  });

  constructor() {
    // The note tool is active on load: move the pointer over the page.
    this.interaction.activateTool('note');
  }
}

@Component({
  selector: 'demo-root',
  imports: [
    EpdfDocumentGate,
    EpdfStage,
    EpdfPageTemplate,
    EpdfRenderLayer,
    EpdfAnnotationLayer,
    Toolbar,
  ],
  providers: [
    provideEmbedPdf(
      { engine: () => localEngine(), initialDocuments: [{ source: ebook }] },
      withStage(),
      withRender(),
      withInteraction(),
      // A preview for the rectangle (off by default for tools you drag), and a fainter one for notes.
      withAnnotation({
        tools: [
          { id: 'square', ghost: true },
          { id: 'note', ghost: { opacity: 0.3 } },
        ],
      }),
    ),
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  styleUrl: './ghost.css',
  encapsulation: ViewEncapsulation.None,
  template: `
    <ng-container *epdfDocumentGate="let document; fallback: loading">
      <demo-toolbar [(opacity)]="opacity" />
      <epdf-stage class="stage" [style.--epdf-ghost-opacity]="opacity()">
        <ng-template epdfPage>
          <epdf-render-layer />
          <epdf-annotation-layer />
        </ng-template>
      </epdf-stage>
    </ng-container>

    <ng-template #loading><p class="loading">Loading…</p></ng-template>
  `,
})
export class App {
  // `--epdf-ghost-opacity` from CSS wins over each tool's own opacity, for every tool.
  protected readonly opacity = signal<number | null>(null);
}

Try it: move the pointer over the page: the note follows it, faintly. Then move the slider.

It shows only where a click would place something. Over an annotation the click selects it, and over text a text tool selects text, so the preview hides there. It hides too when the person may not create annotations. A tool whose click makes nothing, like ink, a polygon, or a tool with clickCreate: false, never shows one. While you press, the preview stays, since letting go is still a click; once you drag, the drawing takes its place.

It’s on by default for tools you use by clicking: stamps, notes, attachments, and the form plugin’s field tools, which show the field a click places (a radio button round, as it will be). It’s off for tools you mostly drag, like shapes and lines, since the size usually comes from the drag. ghost: true turns it on for them.

The cursor and the preview do different jobs. The cursor says which tool is active; the preview says where the annotation will land. You can use either, or both.

Stamps and files#

The stamp and attachment tools ask for a file after the click.

The file dialog comes from a provider feature: add withFilePicker() to provideEmbedPdf(), next to your other features:

file-picker.ts
import { Component } from '@angular/core';
import { withFilePicker } from '@embedpdf/angular/annotation';
import { provideEmbedPdf } from '@embedpdf/angular/runtime';

import { Pages } from './pages';
import { engine, features } from './setup';

@Component({
  selector: 'app-review',
  imports: [Pages],
  providers: [provideEmbedPdf({ engine }, ...features, withFilePicker())],
  template: `<app-pages />`,
})
export class Review {}

Loading live preview…

import {
  ChangeDetectionStrategy,
  Component,
  effect,
  inject,
  untracked,
  ViewEncapsulation,
} from '@angular/core';
import { EpdfDocument, 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 { EpdfInteraction, withInteraction } from '@embedpdf/angular/interaction';
import {
  EpdfAnnotation,
  EpdfAnnotationLayer,
  withAnnotation,
  withFilePicker,
} from '@embedpdf/angular/annotation';
import { localEngine } from '@embedpdf/engine';

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

const TOOLS = [
  { id: 'pointer', label: 'Select' },
  { id: 'stamp', label: 'Stamp' },
  { id: 'attachment', label: 'Attach a file' },
];

@Component({
  selector: 'demo-toolbar',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <div class="toolbar" role="toolbar">
      <div class="segmented" role="group" aria-label="Tool">
        @for (tool of tools; track tool.id) {
          <button
            type="button"
            [attr.aria-pressed]="interaction.activeToolId() === tool.id"
            (click)="interaction.activateTool(tool.id)"
          >
            {{ tool.label }}
          </button>
        }
      </div>
      <p class="hint">
        @if (interaction.activeToolId() === 'stamp') {
          Click the page, then pick a PNG or a JPEG
        } @else if (interaction.activeToolId() === 'attachment') {
          Click the page, then pick any file
        }
      </p>
    </div>
  `,
})
export class Toolbar {
  protected readonly interaction = inject(EpdfInteraction);
  protected readonly tools = TOOLS;
}

@Component({
  selector: 'demo-root',
  imports: [
    EpdfDocumentGate,
    EpdfStage,
    EpdfPageTemplate,
    EpdfRenderLayer,
    EpdfAnnotationLayer,
    Toolbar,
  ],
  providers: [
    provideEmbedPdf(
      { engine: () => localEngine(), initialDocuments: [{ source: ebook }] },
      withStage(),
      withRender(),
      withInteraction(),
      withAnnotation(),
      // The browser's file dialog, for the stamp and attachment tools of every document.
      withFilePicker(),
    ),
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  styleUrl: './file-picker.css',
  encapsulation: ViewEncapsulation.None,
  template: `
    <ng-container *epdfDocumentGate="let document; fallback: loading">
      <demo-toolbar />
      <epdf-stage class="stage">
        <ng-template epdfPage>
          <epdf-render-layer />
          <epdf-annotation-layer />
        </ng-template>
      </epdf-stage>
    </ng-container>

    <ng-template #loading><p class="loading">Loading…</p></ng-template>
  `,
})
export class App {
  private readonly annotation = inject(EpdfAnnotation);
  private readonly interaction = inject(EpdfInteraction);
  private readonly document = inject(EpdfDocument);
  private added = false;

  constructor() {
    // On load: a text file pinned to the cover, and the stamp tool active.
    effect(() => {
      const cover = this.document.pages()[0]?.ref;
      if (this.annotation.status() !== 'ready' || !cover || this.added) return;
      this.added = true;
      untracked(() => {
        const notes = new File(['Questions for the next review.'], 'notes.txt', {
          type: 'text/plain',
        });
        void this.annotation.create(
          cover,
          { subtype: 'file-attachment', rect: { x: 470, y: 232, width: 20, height: 20 } },
          { file: notes },
        );
        this.interaction.activateTool('stamp');
      });
    });
  }
}

Try it: click the page with Stamp, and pick a PNG or a JPEG. The paper clip on the cover is a file attached from code.

To pick from your own library or a cloud drive instead, pass a function. It gets the tool and the spot, and returns the file, or null to cancel:

file-picker-custom.ts
import { Component } from '@angular/core';
import { withFilePicker } from '@embedpdf/angular/annotation';
import { provideEmbedPdf } from '@embedpdf/angular/runtime';

import { Pages } from './pages';
import { engine, features } from './setup';
import { openStampLibrary } from './stamp-library';

@Component({
  selector: 'app-review',
  imports: [Pages],
  providers: [
    provideEmbedPdf(
      { engine },
      ...features,
      withFilePicker(async ({ toolId, page, point }) => {
        if (toolId === 'stamp') return { data: await openStampLibrary() };
        return null;
      }),
    ),
  ],
  template: `<app-pages />`,
})
export class Review {}

A stamp tool can also carry fixed bytes, so a click places it at once:

withAnnotation({
  tools: [{ id: 'approved', extends: 'stamp', source: { kind: 'bytes', source: approvedPng } }],
});

For libraries of stamps, see Stamps.

Methods#

What inject(EpdfAnnotation) gives you for tools and stamps: its tools and stamps parts. The rest is on Annotations in code.

MethodWhat it does
tools.list()Every tool, the built-in ones and yours, so a toolbar can build itself from it. Make your own tool
tools.get(id)One tool, or null
tools.register(tool)Adds a tool while the app runs, or replaces the one with the same id, and returns a function that removes it
tools.getDefaults(id)The fields a tool’s next annotation starts with. In a component, use annotation.tools.defaultsOf(id). Let people change the defaults
tools.updateDefaults(id, changes)Changes a tool’s defaults for the drawings that follow. They stay in this viewer and are never shared.
tools.getProperties(id)What a style panel for the tool shows: { properties, values, mixed }, the same shape as for the selection
stamps.arm(stamp), stamps.disarm()Arms a stamp’s bytes so the next click places them, as the stamp tool does after picking a file, or disarms them. For stamps from a library, use Stamps.
stamps.isArmed()Whether a stamp is armed
stamps.place(stamp, { page, center })Places a stamp’s bytes with its middle on center, without a click. Resolves { annotation }.
setFilePickerProvider(provider)Sets the function that gives the stamp and attachment tools their file, and returns a function that removes it. In a component, use withFilePicker(). Stamps and files

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

Events#

defaults-changed.ts
import { Component, inject } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { EpdfAnnotation } from '@embedpdf/angular/annotation';

import { saveStyle } from './styles';

@Component({
  selector: 'app-save-styles',
  template: '',
})
export class SaveStyles {
  constructor() {
    inject(EpdfAnnotation)
      .tools.defaultsChanged$.pipe(takeUntilDestroyed())
      .subscribe(({ toolId, defaults }) => saveStyle(toolId, defaults));
  }
}
EventFires whenCarries
tools.defaultsChanged$A tool’s defaults changed, from your UI or your codetoolId, defaults

Good to know#

Rotated pages#

On a rotated page, what a tool places looks the way its author saw it. Stamps and text boxes are turned so they read upright. A clicked square or circle keeps its clickCreate size as the page shows (it isn’t turned, its sides swap), and a clicked line points the way its clickCreate says. upright: false turns that off; upright: true turns it on for your own tools.

Touch#

On a touch screen, drawing tools take a single finger: it draws, and two fingers still scroll and zoom. Click tools (notes, stamps) place with a tap, and a drag still scrolls.

Every option#

OptionWhat it is
idThe tool’s name, used with interaction.activateTool(id).
extendsA tool to start from.
subtypeThe kind of annotation it draws, for a tool that doesn’t extend another.
defaultsThe fields every new annotation starts with.
cursorThe cursor while the tool is active.
ghostA preview that follows the pointer: true, false or { opacity }.
clickCreateWhat a single click makes, and which part lands on the click, or false for drag only.
afterCreateSelect the new annotation? Keep the tool? Start typing?
uprightTurn new annotations upright on rotated pages.
sourceFor stamp tools: fixed bytes, or ask for a file.
metaYour own data, such as a label and an icon for a toolbar.
Was this page helpful?

Your feedback goes directly to the documentation team.