embed-pdf-viewer Documentation

Fields that are added, changed or removed have their own events; see
Building forms.

Permissions Copy Chapter

Without it, the fields show their values but can't be changed. A user with a fields:fill
permission for one group fills in that group's fields only: form.canFill(ref) answers per field,
the other fields can't be changed and Tab skips them, validate() leaves them out, and reset()
leaves them as they are. See Signers and groups.

Good to know Copy Chapter

Forms and annotations Copy Section

A field's widgets are the form's: the annotation plugin never lists them. With the
annotation plugin registered, the <FormLayer> and the annotation layer share the page: fields stay fillable with the
pointer tool, and become movable boxes in design mode.

Keyboard Copy Section

Tab moves to the next field in the page's order. In a text box, Enter confirms and Escape puts back
the value it had.

Collecting responses Copy Section

XFA forms Copy Section

Some PDFs also carry a form in the older XFA format. The viewer works with the document's regular
fields and never runs XFA; see Forms.

Signed documents Copy Section

A signature can lock the whole form, or some fields. Locked fields show their values and can't be
changed; see Signatures.

Website Src Content Docs Viewer Features Index (`website/src/content/docs/viewer/features/index.mdx`) Copy Section

title: All features Copy Chapter

{/* Generated from docs/content — edit there, then pnpm docs:sync. */}

All features

Every feature is on from the start. Leave out the ones you don't need with disable, by the name
in the first column:

{ disable: ['forms', 'redaction', 'measurement'] }

Leave features out Copy Chapter

A feature in disable is gone everywhere at once: its buttons, its mode tab, its panel, its menu
rows and its shortcuts. Annotations already in the document still show; people just can't add new
ones. Most features have parts you can turn off on their own, such as forms.building or
documents.download, and one button goes by its command's name, such as tool:highlight.

disable follows its prop, so a feature can come and go while the viewer runs, for example when
a user's plan changes.

Turn features off has every name, read-only, and what to use when: the
layout for where something goes, disable for whether the viewer has it, and the scope for what a
user may do.

Who the user is Copy Chapter

{ identity: { displayName: 'Ada Lovelace' } }

Each feature's settings Copy Chapter

Every feature is a headless plugin, and plugins takes its settings by the plugin's name, exactly
as the plugin's page lists them:

{
  plugins: {
    stage: { spread: 'odd', zoom: { mode: 'fit-width' } },
    search: { highlight: { color: '#a7f3d0' } },
    annotation: { tools: [{ id: 'highlight', defaults: { color: '#fde047' } }] },
  },
}

That opens documents as two-page spreads at the page's width, with green search matches and
yellow highlights. See Plugins for every plugin and how to change its settings
while the viewer runs.

Good to know Copy Chapter

What loads when Copy Section

A feature you disable is still in the viewer's code: disable changes what people see, not what
you ship. The first load stays small another way. Each feature's panels and dialogs are files of
their own, which the viewer fetches in the background once the document shows, so they open at
once. The heavier parts wait until they're used: the signature checks until a signature is
checked, the standard stamps until Stamps opens, the handwriting fonts until someone types a
signature, and each language until it's chosen. How it works
has the whole order.

Cloudpdf Website Src Content Docs Engine Annotations Index (`cloudpdf/website/src/content/docs/engine/annotations/index.mdx`) Copy Section

title: Annotations Copy Chapter

{/* Generated from docs/content — edit there, then pnpm docs:sync. */}

import { Callout } from '@/components/docs/callout';
import { CardGrid, GridCard } from '@/components/docs/cards';

Annotations

Annotations are what people add on top of a page: highlights, sticky notes, shapes, stamps,
free text, links. They're stored in the PDF, so every PDF app shows them, and they stay separate
from the page's own content, so you can change or remove them later.

const page = doc.page(pageRef);

const { annotation } = await page.annotations.create({
  subtype: 'square',
  box: { x: 72, y: 92, width: 200, height: 100 },
  color: '#0078ff',
});

await page.annotations.update(annotation.ref, { contents: 'Check this table' });
await page.annotations.delete(annotation.ref);

Kinds Copy Chapter

Each kind has its own page with an example and its fields:

List annotations Copy Chapter

Every annotation in the document, or the ones on one page:

const { annotations } = await doc.annotations.list(); // every page
const { annotations } = await doc.annotations.list({ pages: [pageA, pageB] }); // some pages
const { annotations } = await doc.page(pageRef).annotations.list(); // one page

A list is cheap even for a whole document: the engine reads the annotations without loading the
pages. Each annotation names its page, and the list's pages has one entry per page it read.

Each annotation has a subtype (its kind), a rect (where it is on its page) and a ref (its
address). Keep the ref: it's how you change or delete the annotation later.

Positions are in points from the top-left corner of the page, with y going down, like every
position in the engine: a box is { x, y, width, height } and a point { x, y }. See
Coordinates.

for (const annotation of annotations) {
  console.log(annotation.subtype, annotation.rect, annotation.contents);
}

A list includes kinds the engine can't create yet: they come back as subtype: 'unsupported',
with their position and common fields. They stay in the PDF untouched.

Form widgets are annotations too, of kind 'widget', but they're the form's: a list here never
holds one, and doc.forms.list() returns them with the fields. You place and change them through
the form; see Creating form fields.

Fields every annotation has Copy Chapter

Besides subtype, rect and ref, every kind has these fields:

Each annotation also has the flags and the fields that say who wrote it.

Add an annotation Copy Chapter

create() takes the kind and its fields, and returns the new annotation:

const { annotation } = await page.annotations.create({
  subtype: 'circle',
  box: { x: 60, y: 392, width: 120, height: 100 },
  interiorColor: '#1e90ff',
});

Fields you leave out get the kind's default. The engine draws the annotation's appearance for
you, so it shows the same in every PDF app.

Stamps and file attachments also carry bytes (an image, a file). Pass those in a second
argument; see Stamps and
File attachments.

Change an annotation Copy Chapter

update() takes the ref and only the fields you want to change:

await page.annotations.update(annotation.ref, {
  color: '#dc143c',
  contents: 'Reviewed',
});

A field you leave out keeps its value. A field set to null is removed, for example
{ interiorColor: null } for no fill. A field's value is replaced whole (a file, a list of
points), except rich text's body style, which merges.

You can also pass an annotation you read straight back: every field it has is one update()
accepts. That makes "change a copy, then save it" code simple:

await page.annotations.update(annotation.ref, { ...annotation, opacity: 0.5 });

Fields the engine writes (author, the dates, userId, ref…) are accepted and ignored. For
free text, send contents or richText, not both with different text.

Move or resize by `rect` Copy Section

An update takes a new rect for every annotation, as a script's annot.rect does in Acrobat. A
note, a file, a link, a popup and a redaction take it as it is.

Every other annotation is drawn from its shape: rectangles, ellipses, text boxes, stamps, carets
and form fields' widgets from their box, lines, polylines, polygons and ink from their points,
and text markup from its quads. For these, a new rect puts the shape there: each point is mapped from the old
rect onto the new one, each axis on its own. A rect of the same size moves the drawing, and a
bigger one stretches it:

const { rect } = line;

// 40 points right, 20 down
await page.annotations.update(line.ref, {
  rect: { ...rect, x: rect.x + 40, y: rect.y + 20 },
});

The engine then works out rect again from the shape. After a resize it can differ a little from
the one you sent: a line keeps its width, and its endings keep their size. The rect you read,
sent back, changes nothing, so a read passed straight back works.

• A new rect with a new shape (box, points or quads) fails with InvalidArg: send one or the
  other.
• A turned drawing can only move. A rect of another size fails with InvalidArg; resize its
  box or its points instead. A box at a quarter turn is the exception: it stands upright on the
  page, so a rect resizes it along its own sides.
• A rect that would squash a drawing to no width or no height fails with InvalidArg.

shapeForRect(annotation, rect) gives the fields that put an annotation at a rect, by the same
rule. Use it to place a copy somewhere else:

import { shapeForRect } from '@cloudpdf/engine';

await page.annotations.create({ ...copy, ...shapeForRect(copy, target) });

A create works out a drawn annotation's rect from its shape, whatever rect you send, so a
copy of another app's drawing keeps its shape exactly. A box turned a quarter can be created by
its rect instead of its box; see Turned shapes.

Delete and reorder Copy Chapter

await page.annotations.delete(annotation.ref);

await page.annotations.reorder([annotation.ref], 'start'); // to the back
await page.annotations.reorder([annotation.ref], { after: other.ref }); // just above another

Deleting an annotation also deletes its popup, if it has one, and its replies; see
Delete a note.

Annotations on a page are drawn in order, so the last one is on top. reorder(refs, position)
moves annotations together, in the order you pass them, right after or before another annotation
of the page, or to the back ('start') or the front ('end'). It resolves the page's new order,
order, as refs, and fires annotations.reordered.

Widgets are drawn above every annotation, in an order of their own, so a widget is never a
neighbour here: reorder() refuses one with InvalidArg. Restack widgets with
doc.forms.reorderWidgets().

Style Copy Chapter

Most kinds share the same style fields:

A pattern alone doesn't make a border dashed: a 'solid' border keeps its dashArray and draws
solid. dashArray: null on a dashed border draws the default [3], 3 points on and 3 off. A
border from another app can read 'beveled' or 'inset'; only form widgets draw those, so a
write takes them only sent back unchanged.

Colors are '#rrggbb', as in CSS: the engine gives them in lowercase and takes either case. They
never include transparency: that's what opacity is for. The default color depends on the kind
(yellow for a highlight, red for a shape, black for free text); each kind's page lists its
defaults.

A PDF can store a color as gray or CMYK. It reads as the same color in '#rrggbb', and sent back
unchanged it stays as the file has it, so passing a read straight back rewrites nothing.

Who wrote it Copy Chapter

The engine records who created and last changed each annotation, from the user the document was
opened for. You read these fields; you don't set them:

Flags Copy Chapter

Every annotation has the standard PDF flags as true/false fields. Set the ones you need; the
rest stay off (on create) or keep their value (on update). The exception is print: a new
annotation prints unless you set print: false, as in Acrobat. A popup doesn't print.

await page.annotations.update(annotation.ref, { print: true, locked: true });

Flags are instructions for PDF apps. The engine itself still lets you change a locked
annotation; the viewer's annotation tools respect the flags in their interface.

Permissions Copy Chapter

Reading annotations needs doc.annotate.read. Creating, changing and deleting them needs a
permission for that action, which can be limited to the user's own annotations:
annotations:update:self lets a user edit what they created and nothing else. See
Permissions.

More Copy Chapter

• Import & export: copy annotations to another
  document, or store them apart from the PDF.
• Drawing annotations yourself: render annotations as
  separate images, bake them into the page, or export them as a PDF.
• Refs & identity: what a ref contains, and why you never
  build one.
• Changes & undo: make several annotation edits as one action,
  and undo them.

Cloudpdf Website Src Content Docs Engine Forms Index (`cloudpdf/website/src/content/docs/engine/forms/index.mdx`) Copy Section

title: Forms Copy Chapter

{/* Generated from docs/content — edit there, then pnpm docs:sync. */}

Forms

A PDF form is a set of fields: text boxes, checkboxes, radio buttons, dropdowns and lists. The
engine reads every field with its value, fills fields in, and redraws them so the new value shows
in every PDF app.

const { fields } = await doc.forms.list();

const name = fields.find((field) => field.name === 'billing.name')!;
await doc.forms.setValue(name.ref, { value: 'Ada Lovelace' });

Read the form Copy Chapter

list() returns every field in the document:

const { fields } = await doc.forms.list();

for (const field of fields) {
  console.log(field.name, field.family);
}

Every field has these:

A document without a form returns an empty fields. The list's formKind says what the document
has: 'none', 'acroform' (a regular PDF form) or 'xfa' (see Good to know).

The list also has needsAppearances, true when the form asks PDF apps to draw its fields
themselves (repair() can clear it), and
calculationOrder (see Calculations).

Values Copy Section

Each family has its own value fields. Check family first, and TypeScript knows which ones the
field has:

if (field.family === 'text') console.log(field.value); // string
if (field.family === 'checkbox') console.log(field.checked); // boolean
if (field.family === 'listbox') console.log(field.selectedValues); // string[]

Each option of a dropdown (combobox) or list is { label, value, selected }. label is what the
user sees; value is what the form stores, and what you pass when you fill the field in.

Who created and filled it in Copy Section

A field records who created it and who last filled it in, from the identity the document was opened
with:

field.createdBy; // 'user-17': who created the field, or null
field.filledBy; // 'user-42': whose fill last changed the value
field.filledByName; // 'Ann de Vries'
field.filledAt; // '2026-10-08T10:42:00Z'

The engine stamps these; a write can't set them. A fill that leaves the value as it was changes
none of them, and undoing a fill puts the previous ones back. A widget has no attribution of its own:
its field's is the one.

Widgets Copy Section

A field shows on a page through a widget: the box you see and click. Most fields have one. A
radio group is one field with a widget per button, and a field repeated on every page (a
reference number in the header, say) has a widget per page, all showing the same value.

Each widget in field.widgets has its page and its ref. The form also lists every widget in
widgets: where it is (rect, in points from the page's top-left), how it looks, its state,
what it does when clicked (actions), and the ref of the field it belongs to (field). So one read is enough to draw your own form layer
over a page:

const { widgets } = await doc.forms.list();

for (const widget of widgets) drawBox(widget.page, widget.rect, widget.field);

Checkbox and radio widgets in field.widgets also have their exportValue (what the form data
holds when this widget is checked) and checked.

A form field's widgets come with the form, never with the annotations: page.annotations.list()
doesn't return them, and reading them takes doc.forms.read, not doc.annotate.read. Each page's
widget images, every look and state, come from page.forms.renderAppearances().

Find a field Copy Chapter

The ref from list() is the best address: it keeps working when the field is renamed. When you
know a field by its name instead (from your backend, or from data you stored), make a ref from the name:

import { toFieldRef } from '@cloudpdf/engine';

const field = await doc.forms.get(toFieldRef('billing.name'));

The name is the full name, with dots between the groups. A field that isn't there fails with
NotFound.

Fill in a field Copy Chapter

setValue() takes the field's ref and its new value, in the same fields a read returns. What
you read, you can write back:

await doc.forms.setValue(name.ref, { value: 'Ada Lovelace' }); // text
await doc.forms.setValue(agree.ref, { checked: true }); // checkbox
await doc.forms.setValue(plan.ref, { value: 'yearly' }); // radio group
await doc.forms.setValue(country.ref, { value: 'NL' }); // dropdown
await doc.forms.setValue(toppings.ref, { selectedValues: ['cheese', 'olives'] }); // list

setValue() returns the field as it is now:

const { field } = await doc.forms.setValue(name.ref, { value: 'Ada' });

The engine redraws the field's widgets, so the page shows the new value in every PDF app. Render
the page again to see it.

What the engine checks Copy Section

The engine checks a value before it writes anything. A call that fails with InvalidArg leaves
the field as it was:

• The value must be the family's own: { checked: true } on a text field fails.
• A dropdown or list takes option values, not labels. A dropdown with edit: true also takes
  free text. More than one value needs a list with multiSelect.
• A radio group's value must be the export value of one of its buttons.
• A radio group with noToggleToOff can't be cleared once a button is chosen.
• Push buttons and signature fields hold no value you can set.

Some things are fixed up rather than refused: text longer than maxLength is cut to fit, and
in a radio group with radiosInUnison, the buttons that share an export value check together.

readOnly is an instruction for PDF apps: they don't let the user change the field. The engine
still accepts your own writes, for example a total your code calculates.

Reset Copy Chapter

reset() puts back each field's defaultValue, or empties it when it has none. Without an
argument it resets the whole form; pass a ref, or a list of refs, to reset only those fields:

await doc.forms.reset(); // every field
await doc.forms.reset(name.ref);
await doc.forms.reset([name.ref, email.ref]);

It returns the fields it changed, as they are now. A field that already holds its default is
left alone and isn't in the list:

const { fields } = await doc.forms.reset();

console.log(`${fields.length} fields reset`);

Fields that hold no value, such as push buttons and signature fields, are skipped. Resetting the
whole form also skips the fields a signature locked and fields stored inline;
name one of those yourself and the call fails, the same as a setValue() would.

Move fields and values between documents Copy Chapter

export() takes fields out as one bundle, each with its value. importValues() fills another
document's fields of the same name from it, and import() copies the fields themselves:

const bundle = await doc.forms.export();

const { fields, dropped } = await other.forms.importValues(bundle);

Each value is checked like a setValue(). A field the document doesn't have, a value it can't
take, or a field a signature locked is left out and listed in dropped; the rest still land, as
one change you can undo. See Import & export.

Events Copy Chapter

setValue(), reset() and importValues() fire forms.valueSet, one per field that changed.
Each carries what the call returned for that field:

doc.events.on('forms.valueSet', ({ field }) => {
  updateSummary(field);
});

When one call changes several fields, such as reset() or importValues(), their events share
origin.tx, like an annotation import.

Permissions Copy Chapter

Reading the form needs doc.forms.read, and exporting it doc.download too. Filling in,
resetting and importing values needs doc.forms.fill, which includes doc.forms.read. See
Permissions.

A signed document can take filling away, for the whole form or for single fields. The call then
fails with ProtectedDocument; see
Digital signatures.

More Copy Chapter

• Creating form fields: add fields and widgets, change and delete
  them, repair a broken form.
• Import & export: copy fields from one document to another,
  or fill a form in from a bundle.
• Digital signatures: sign a signature field and check the
  signatures in a document.
• Changes & undo: fill in several fields as one action, and
  undo it.

Good to know Copy Chapter

Calculations, formatting and validation Copy Section

The engine doesn't run the form's JavaScript. setValue() stores the value you give it: it
doesn't recalculate a total, format a date or an amount, or run a validation script. PDF apps run
those scripts while a user types.

A field's scripts are in field.actions (keystroke, format, validate and calculate), and
the list's calculationOrder holds the fields whose totals are calculated, in order. To write them,
see Scripts and calculations.

The viewer's form plugin runs these scripts and writes their results as one
change: forms.setValue, forms.reset, forms.setDisplay
(whether the field shows and prints) and forms.setAppearanceText (the formatted text the field
shows, while its value stays the same) ops, in the order the scripts asked for them. All of them
are written, or none is: a field a signature locked refuses the whole change. You only need these
ops when you run form scripts yourself.

Recovered fields Copy Section

Some PDFs have fields that show on the page but are missing from the form's list of fields, a
bug in the tool that made them. The engine finds them anyway: they come back with
origin: 'recovered' and fill in like any other field. Other PDF apps may not see them;
repair() fixes the file.

A field on several pages Copy Section

A field's widgets can be on different pages. The meta of a setValue() or reset() result
lists every widget whose look changed, with its page (meta.changedWidgets). For a radio group
that's the button switched off and the one switched on. Use it to render only the pages that
changed.

meta.redrawnWidgets lists those whose picture the engine drew again, such as a text field's
widgets after a new value. A checkbox or radio button that switches shows another picture it
already has, so it isn't in the list.

Checkboxes with several widgets Copy Section

A checkbox can have several widgets, each with its own exportValue: a "Yes / No" pair, for
example. { checked: true } checks the first widget; { value: 'No' } checks the widget with
that export value.

In the file, each checkbox and radio widget also has an onState: the name of its checked look
(PDF's appearance state). It's usually the same as the export value, and widgets the engine
creates always use their exportValue for it. You never need it to fill a field in.

The field's value in the file (valueEntry) is the checked widget's onState, or 'Off', as the
PDF standard says. Some tools write the widget's position instead ('0', '1'); such a value
still resets to that widget.

XFA forms Copy Section

formKind is 'xfa' when the PDF also carries an XFA form, an older XML form format. The
engine works with the document's regular fields and never runs XFA.

Fields stored inline Copy Section

A field that the file stores inside another object, rather than as an object of its own, can be
read but not changed: writes fail with InvalidArg. PDF tools rarely write fields this way.

Cloudpdf Website Src Content Docs Headless Annotations Index (`cloudpdf/website/src/content/docs/headless/annotations/index.mdx`) Copy Section

title: Annotations Copy Chapter

{/* Generated from docs/content — edit there, then pnpm docs:sync. */}

import { Cards, Card } from '@/components/docs/cards';

{/* This page is served at …/headless/<framework>/annotations with NO trailing
slash, so a relative href resolves against …/headless/<framework>/.
Sibling pages are annotations/tools, other sections text/selection. */}

Annotations

Annotations are what people add on top of a page: highlights, sticky notes, shapes, stamps and
text boxes. The annotation plugin shows the ones a PDF already has, lets people draw and edit new
ones, and gives your code the same abilities. Every annotation is saved into the PDF, so it looks
the same in every other PDF app.

Show the annotations in a PDF Copy Chapter

Register interactionPlugin() and annotationPlugin(), then put an <AnnotationLayer> above the
rendered page:

const initialDocuments = [
  { source: contract, identity: { userId: 'bot', displayName: 'Import job' } },
];

effect(() => viewer.updateSettings({ identity: auth.identity() }));