# Technical Documentation: embedpdf/embed-pdf-viewer
> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/embedpdf/embed-pdf-viewer)
### Overview (README.md)
> [!WARNING]
> **EmbedPDF v3 is under active development and is not yet recommended for production use.** For the current stable release, use the [`v2` branch](https://github.com/embedpdf/embed-pdf-viewer/tree/v2).
# Open‑Source JavaScript PDF Viewer
**EmbedPDF** is a framework‑agnostic, Apache‑2.0‑licensed PDF viewer that drops into _any_ JavaScript project. Whether you build with **React, Vue, Svelte, Preact,** or vanilla JS, EmbedPDF delivers a smooth, modern reading experience and a clean developer API.
---
## 📚 Documentation
Full docs, installation guides, API reference, and examples:
👉 **[https://www.embedpdf.com](https://www.embedpdf.com)**
## 🚀 Live Demo
Try it now — load your own PDF or use the sample:
👉 **[https://app.embedpdf.com](https://app.embedpdf.com)**
---
## 💖 Sponsors
We are grateful for the support of our sponsors!
### Silver Sponsors
### Bronze Sponsors
---
## ✨ Features
- Annotations (highlight, sticky notes, free text, ink)
- True redaction (content is actually removed)
- Search, text selection, zoom, rotation
- Smooth, virtualized scrolling
- Pluggable architecture & tree-shakable plugins
## 🤝 Contributing
We love contributions! To get started, read our [contributing guide](CONTRIBUTING.md) and jump into the [GitHub discussions](https://github.com/embedpdf/embed-pdf-viewer/discussions).
## 📄 License
Everything in this repository is licensed under the [Apache License, Version 2.0](LICENSE), with one exception: [`cloudpdf/server`](cloudpdf/server) — the self-hostable CloudPDF server — is **Fair Source**, under the [Fair Core License, FCL-1.0-ALv2](cloudpdf/server/LICENSE). Its source may be inspected, copied, and modified for purposes permitted by the FCL. **That does not make the server free to run:** while a release remains under the FCL, running or self-hosting it requires a valid CloudPDF license (a license key for a connected deployment or a signed certificate for an air-gapped deployment). You may not move, change, disable, or circumvent the license-key functionality; enable protected functionality without a valid license; or remove protected functionality. Competing Uses, as defined in the FCL, are also prohibited. Each release automatically becomes Apache-2.0 two years after publication. See [LICENSING.md](LICENSING.md) for the full licensing map, including website content.
## Third-Party Licenses
The engine is powered by [EmbedPDF Runtime](https://github.com/embedpdf/runtime), our fork of [PDFium](https://pdfium.googlesource.com/pdfium/), which is licensed under the [Apache License, Version 2.0](https://pdfium.googlesource.com/pdfium/+/refs/heads/main/LICENSE). PDFium is a Google project; EmbedPDF is not affiliated with or endorsed by Google.
---
### Conventions README (`docs/conventions/README.md`)
# Conventions
How the EmbedPDF client stack is built, and the rules every change follows.
These documents describe the code as it is. When the code and a document
disagree, fix one of them in the same pull request.
Start with this page, then read [`architecture.md`](./architecture.md).
## The model
A plugin provides one capability per scope (the workspace, or each open
document). The capability is its only public surface: synchronous reads,
verbs that do work, and events. A plugin talks to the engine only through
`ctx.doc`, and to other plugins only through their capabilities.
### Four kinds of state
| Kind | What it is | Home | How it changes |
| -------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Mirror | A local copy of data the engine owns | `ctx.mirror(spec)`, `ctx.pageMirror(spec)` | Only by folding confirmed engine events (every origin) and by loads |
| Pending change | A change this session staged that the engine hasn't answered | the document's change queue (`ctx.changes`), shown by mirrors' `view()` | Staged by a verb or gesture; leaves the views once answered and held, or refused |
| Session | State the client owns that is not in the PDF | `ctx.state` | Only through named pure transitions in `model.ts` |
| Resource | Handles, rasters, workers, registries of functions, caches | closures, owned through `ctx.cleanup` and `ctx.acquire` | Any way; readers are woken with `ctx.notify()` |
### Three kinds of events
| Kind | Meaning | Fired from |
| ------------ | ------------------------------------ | ------------------------------------------------------------------ |
| Fact | Something changed in the document | Where the confirmed document event is applied, with `event.origin` |
| State change | A session value changed | The plugin's one `ctx.state.onChange` listener |
| Occurrence | An operation ran, finished or failed | Where the operation reaches that point |
## Core rules
1. A capability is a plugin's only public surface. Other plugins and adapters
read through it, never through a plugin's state.
2. Every piece of state has one kind and one home: mirror, pending change,
session or resource. State is plain data; everything else is a resource.
3. A mirror changes only by its fold and by loads. Its fold is pure and the
same for every origin. Verbs never write it.
4. Session state changes only through named pure transitions applied with
`ctx.state.update`. A transition that returns the same object changes
nothing.
5. A verb calls the engine and returns. The engine publishes the confirmed
event before the call resolves, so the verb's `await` already sees its own
write: no refetch, no waiting, no hand-made events.
6. Every event fires from exactly one place. Fact events carry
`event.origin` as it is; no plugin builds an origin by hand. Loads announce
`onResynced`.
7. Reads are synchronous, pure and identity-stable (`memo`, `memoByKey`).
They never start engine work.
8. A plugin declares every token it resolves in `requires` or `optional`, and
imports sibling tokens from their `/contract` entries.
9. Registrations with siblings and subscriptions happen in `connect`, and
everything acquired is owned: `ctx.cleanup`, `ctx.listen`, `ctx.acquire`.
10. A capability rejects with `PluginError` only, and every verb that can
refuse has a `can*` twin.
11. Names and comments follow [`naming.md`](./naming.md) and
[`comments.md`](./comments.md).
## Map
| File | Covers |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| [`architecture.md`](./architecture.md) | Layers, scopes and bring-up, the four kinds of state, data flow, reads, reactions, pure cores, plugin anatomy |
| [`state-and-sync.md`](./state-and-sync.md) | `ctx.state`, `notify`, `watch`, `waitFor`, mirrors, page mirrors, pending changes, resources, reactions, the sync rules |
| [`events.md`](./events.md) | Fact, state-change and occurrence events, event sources, naming, `EventOrigin`, `onResynced`, subscribing |
| [`plugins.md`](./plugins.md) | Plugin files, manifest, tokens and contracts, package entries, controller, `connect`, dependencies, lifetime, errors, a complete example |
| [`testing.md`](./testing.md) | Where tests live, the test context, fake engines, mirror tests, kernel tests, conformance suites, type tests |
| [`naming.md`](./naming.md) | Identifiers, the glossary, type suffixes, the capability vocabulary |
| [`comments.md`](./comments.md) | What a comment may say, and how it is checked |
| [`packages.md`](./packages.md) | Where a package lives and what it is called |
| [`permissions.md`](./permissions.md) | Authorization-aware plugins: `can*` twins, gates, per-record authority |
| [`viewer-doors.md`](./viewer-doors.md) | One viewer, several deliveries: the entry points that choose the engine |
| [`engine-services.md`](./engine-services.md) | Layout of `@embedpdf/engine-services`: readers, mutators, the worker host |
| [`runtime-confinement.md`](./runtime-confinement.md) | Thread-confined PDFium: per-thread state, the worker pool, the threading gate |
| [`engine-host-isolation.md`](./engine-host-isolation.md) | Running engines in supervised child processes, and the threat model |
| [`server-adapters.md`](./server-adapters.md) | The CloudPDF server's adapter families: secrets, KMS, storage, CDN, import |
| [`server-migrations.md`](./server-migrations.md) | Forward and rollback database migrations for the CloudPDF server |
| [`docs-architecture.md`](./docs-architecture.md) | How the documentation site renders one source per framework |
Package build and export rules are in
[`tooling/build/README.md`](../../tooling/build/README.md). Changesets are
described in [`.agents/skills/embedpdf-changesets/SKILL.md`](../../.agents/skills/embedpdf-changesets/SKILL.md).
---
### Content Engine Index (`docs/content/engine/index.mdx`)
---
title: Engine
description: Open, read, change and save PDF files from JavaScript, with one typed API.
---
import { Cards, Card } from '@/components/docs/cards';
# The PDF engine
The EmbedPDF engine opens PDF files in the browser and lets you render their pages, read and
search their text, add annotations, fill forms, edit pages and save the result. It runs PDFium,
the PDF library inside Chrome, in a Web Worker, so your page stays responsive. Nothing is
uploaded: the file never leaves the device.
The ready-made viewer and the headless components are built on this engine. Use it directly
when you want PDF features without a viewer: a thumbnail job, a form filler, an export script.
The CloudPDF engine gives your app a full PDF engine over HTTPS. Your files stay on your
CloudPDF server. The engine renders their pages, reads and searches their text, stores
annotations and form values, and checks every call against the permissions in the user's
token.
The CloudPDF viewer and the headless components are built on this engine. Use it directly when
you want PDF features without a viewer: a thumbnail job, a form filler, an export script.
```ts
import { localEngine } from '@embedpdf/engine';
const engine = localEngine();
const doc = await engine.open({ kind: 'bytes', bytes });
const { pages } = await doc.pages.list();
const image = await doc.page(pages[0].ref).render.image();
```
```ts
import { cloudEngine } from '@cloudpdf/engine';
const engine = cloudEngine();
const doc = await engine.open({ kind: 'token', token: () => fetchDocumentToken(documentId) });
const { pages } = await doc.pages.list();
const image = await doc.page(pages[0].ref).render.image();
```
## What you can do
- **[Render pages](/docs/engine/documents/rendering)** as images, at any size.
- **[Read](/docs/engine/text/extraction), [search](/docs/engine/text/search) and
[select](/docs/engine/text/selection-and-geometry)** the text on a page, and find out where
each character is.
- **[Add and edit annotations](/docs/engine/annotations)**: highlights, notes, shapes, stamps,
measurements. Copy them to another document with
[import & export](/docs/engine/annotations/import-export).
- **[Fill forms](/docs/engine/forms)**, create form fields and
[sign](/docs/engine/forms/signatures) documents.
- **[Change pages](/docs/engine/documents/pages)**: rotate, reorder, delete, insert, merge and
split.
- **[Redact](/docs/engine/documents/redaction)** content for good, and
**[save](/docs/engine/documents/saving)** the result.
- **[Group edits into changes](/docs/engine/documents/changes)** that apply all or none, and undo
or redo any of them.
Every call is async, can be cancelled, and fails with a typed error you can branch on. The same
code runs on the local engine and on the CloudPDF engine: only how you create the engine and
open a file differs.
A few things exist only on the local engine: its fonts, `warmup()`, raw pixels, and saving a
document's layer or to a file. A document opened with `localEngine()` has them. Code that takes
any engine checks first:
```ts
import { isLocalDocument } from '@embedpdf/engine';
if (isLocalDocument(doc)) {
const layer = await doc.downloadLayer();
}
```
`isLocalEngine(engine)` does the same for an engine.
## Local or cloud
This engine runs in the browser: no server, no upload, and it works offline. That makes it the
right choice when the user already has the file, or when the file may not leave their device.
When the file lives on your server, the CloudPDF engine runs the same API there and checks every
call. A user sees the first page as an image, without downloading the whole PDF or the engine
(about 3 MB compressed), and a user who may not download the file never receives it. Your code
stays the same: swap `localEngine()` for `cloudEngine()`.
## Next steps
---
### Content Headless Index (`docs/content/headless/index.mdx`)
---
title: Headless
description: Build your own PDF viewer from plugins, components and hooks, in React, Vue, Svelte or Angular.
---
import { Cards, Card } from '@/components/docs/cards';
{/* Served at `…/headless/` with NO trailing slash: a relative href
resolves against `…/headless/`, so pages are `quick-start`,
`viewing/stage`, `concepts/how-it-works`. */}
# Build your own PDF viewer
The headless packages give you everything a PDF viewer does, without a look of their own: pages
that scroll and zoom, crisp rendering, text selection and search, annotations, forms and
signatures. You build the interface in , and nothing appears on screen unless you put
it there.
That's a complete viewer: the pages scroll, zoom with a pinch or Ctrl and the wheel, and stay sharp
at every zoom. Everything else is a plugin you add, and a few lines of your own UI.
## Headless or the ready-made Viewer?
EmbedPDF comes in two forms, built on the same engine and plugins:
- **The [Viewer](/docs/viewer)** is finished: a toolbar, sidebars, annotation tools and search,
ready in minutes. You configure it and theme it.
- **Headless** is the parts: you decide what the toolbar looks like, where the search box goes, and
what happens when someone clicks an annotation.
Choose headless when the viewer is part of your product's own interface. You can start with the
Viewer and move to headless later: the plugins and their options are the same.
## How it's put together
A headless viewer has five parts. You meet them on every page:
- **The engine** opens and reads PDF files. It runs in the browser, or on your server with
CloudPDF.
- **``** starts the engine, opens documents, and holds the plugins.
- **Plugins** add one feature each: search, annotations, forms. Register the ones you need; the
rest never reach your bundle.
- **Layers** draw inside each page: the page itself, the text selection, the annotations.
- **Hooks****Composables****Functions****Services** connect your own UI: `useSearch()`
to search, `useSearchState()` to show the results, `useSearchEvent()` to react when something
happens.`inject(EpdfSearch)` gives you the plugin's methods to search,
its values as signals to show the results (`search.hitCount()`), and its events as streams to
react when something happens (`search.completed$`).
[How it works](concepts/how-it-works) explains each in a few minutes.
## Every plugin
Each plugin is one import line. Registering a plugin and importing its components come from the
same place:
| Plugin | What it gives you | Import from |
| :-- | :-- | :-- |
| [Stage](viewing/stage) | Scrolling, zoom, layouts, page navigation | `@embedpdf/react/stage` |
| [Render](viewing/render) | Sharp pages at every zoom, deep-zoom tiles | `@embedpdf/react/render` |
| [Links](viewing/links) | Clickable links to pages and websites | `@embedpdf/react/link` |
| [Selection](text/selection) | Selecting and copying text | `@embedpdf/react/selection` |
| [Search](text/search) | Finding text, and showing every match | `@embedpdf/react/search` |
| [Annotations](annotations) | Highlights, notes, shapes, free text, and your own tools | `@embedpdf/react/annotation` |
| [Stamps](annotations/stamps) | Libraries of stamps, placed by click or by code | `@embedpdf/react/stamp` |
| [Measurements](annotations/measurements) | Distances, perimeters and areas at a real scale | `@embedpdf/react/measurement` |
| [Redaction](annotations/redaction) | Removing content for good | `@embedpdf/react/redaction` |
| [Forms](forms) | Filling and building PDF forms | `@embedpdf/react/form` |
| [Signatures](forms/signatures) | Signing documents and checking signatures | `@embedpdf/react/signature` |
| [Page edit](documents/pages) | Rotating, reordering, inserting and deleting pages | `@embedpdf/react/page-edit` |
| [Metadata](documents/metadata) | A document's title, author and your own fields | `@embedpdf/react/metadata` |
| [Actions](documents/actions) | What a PDF does by itself: buttons, scripts, printing | `@embedpdf/react/actions` |
| [View manager](documents/tabs) | Several documents side by side | `@embedpdf/react/view-manager` |
| [Interaction](ui/tools) | The active tool, cursors and touch | `@embedpdf/react/interaction` |
| [Commands](ui/commands) | Named actions with labels, icons and shortcuts | `@embedpdf/react/commands` |
| [Shell](ui/panels) | Which panels, dialogs and menus are open | `@embedpdf/react/shell` |
| [Translations](ui/translations) | Your UI in the user's language | `@embedpdf/react/i18n` |
## Local or cloud
The same viewer runs on either engine. Only how you create the engine and open a document differs;
every plugin, and component stays the same.
The local engine runs in the browser: no server, no upload, and it works offline. It's the right
choice when the user already has the file, or when the file may not leave their device.
With the CloudPDF engine, the file stays on your server and pages arrive as images, so the first
page shows at once, without downloading the whole PDF or the engine. Every call is checked on the
server, several people can review one document together, and every change is stored as it's made.
Your viewer stays the same: swap `localEngine()` for `cloudEngine()`.
The CloudPDF engine keeps the file on your server. Pages arrive as images, so the first page
shows at once; every call is checked against the user's token; and annotations and form values are
stored as people make them, with everyone who has the document open seeing each other's changes.
## Next steps
---
### Content Viewer Index (`docs/content/viewer/index.mdx`)
---
title: Viewer
description: A complete PDF viewer you add with one tag, then make your own with a few lines of config, in plain HTML, React, Vue, Svelte or Angular.
---
import { Cards, Card } from '@/components/docs/cards';
{/* Served at `…/viewer/` with NO trailing slash: a relative href
resolves against `…/viewer/`, so pages are `quick-start`,
`customize/layout`, `concepts/how-it-works`. */}
# A complete PDF viewer, ready to embed
The viewer is everything people expect from a PDF app, in one tag: a toolbar, thumbnails, search,
annotations, comments, forms, signatures and stamps. It fits a phone and a wide screen, speaks the
user's language, and works with a keyboard and a screen reader.
That's the whole integration. The rest of these docs are about making it yours.
## Make it yours
Everything you change is a few lines of config, the same in every framework. Start at the top and
stop when it's enough:
| You want to | Change | Page |
| :-- | :-- | :-- |
| Match your brand | Your accent color, fonts, light or dark | [Theming](customize/theming) |
| Leave features out, or make it read-only | `disable: ['forms', 'redaction']`, `readOnly: true` | [Turn features off](features/turning-off) |
| Move or remove buttons | One line per change | [Layout](customize/layout) |
| Put a toolbar at the bottom, on the side, or several | Where each bar goes | [Layout](customize/layout) |
| Add your own button | A command: a label, an icon, what it does | [Buttons & commands](customize/commands) |
| Add your own menu or panel | A list of items, or your component | [Menus](customize/menus), [Panels](customize/panels) |
| Put your own component in the toolbar | Your React, Vue, Svelte or Angular component | [Your own components](customize/components) |
| Control the viewer from your app | The `viewer` object | [The viewer in code](code/viewer) |
You never write layout code for phones, menus that open the right way, or keyboard focus. You say
what goes where, and the viewer takes care of how it behaves. A menu in a bottom toolbar opens
upward; the thumbnails slide up from the bottom on a phone; a button that doesn't fit moves into
the "More" menu.
## The viewer or headless?
EmbedPDF comes in two forms, built on the same engine and the same plugins:
- **The viewer** is finished. You configure it, theme it, and add your own buttons, menus, panels
and components.
- **[Headless](/docs/headless)** is the parts. You build the whole interface yourself, and
nothing appears on screen unless you put it there.
Start with the viewer. Every feature is a [headless plugin](code/plugins) with the same settings,
and inside the viewer your own components can use the headless hooks. If you outgrow the viewer,
what you learned still applies.
## Local or cloud
The viewer runs on the local engine by default: the PDF opens in the browser, with no server and no
upload, and it works offline.
With CloudPDF, the file stays on your server and pages arrive as images, so the first page shows
at once, without downloading the whole PDF or the engine. Every action is checked on the server,
and annotations and comments are shared live between everyone who has the document open. The
viewer and your config stay the same.
## The CloudPDF viewer
The file stays on your server. Pages arrive as images, so the first page shows at once; every
action is checked against the user's token; and annotations, comments and form values are stored
as people make them, with everyone who has the document open seeing each other's changes.
## Next steps
---
### Content Engine Annotations Index (`docs/content/engine/annotations/index.mdx`)
---
title: Annotations
description: List, add, change, reorder and delete annotations, with the fields and styles every kind shares.
---
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.
```ts
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
Each kind has its own page with an example and its fields:
## List annotations
Every annotation in the document, or the ones on one page:
```ts
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](/docs/engine/concepts/coordinates).
```ts
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](/docs/engine/forms/authoring).
## Fields every annotation has
Besides `subtype`, `rect` and `ref`, every kind has these fields:
| Field | What it is |
| :--------- | :------------------------------------------------------------------------------------------------------- |
| `contents` | A comment, the text PDF apps show for the annotation. |
| `subject` | A short title PDF apps show with the comment, such as `'Question'`. |
| `nm` | A unique name on its page. See [Refs & identity](/docs/engine/concepts/identity). |
| `reply` | The annotation it answers, or `null`. See [Notes & replies](/docs/engine/annotations/notes-and-replies). |
| `popup` | The ref of its popup window, or `null`. See [Popups](/docs/engine/annotations/notes-and-replies#popups). |
| `groupId` | The group it belongs to, when you work with groups. |
Each annotation also has the [flags](#flags) and the fields that say [who wrote it](#who-wrote-it).
## Add an annotation
`create()` takes the kind and its fields, and returns the new annotation:
```ts
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](/docs/engine/annotations/stamps) and
[File attachments](/docs/engine/annotations/file-attachments).
## Change an annotation
`update()` takes the `ref` and only the fields you want to change:
```ts
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:
```ts
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`
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:
```ts
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:
```ts
import { shapeForRect } from '@embedpdf/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](/docs/engine/annotations/shapes#turned-shapes).
## Delete and reorder
```ts
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](/docs/engine/annotations/notes-and-replies#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()`](/docs/engine/forms/authoring#move-and-style-widgets).
## Style
Most kinds share the same style fields:
| Field | What it is | Default |
| :-------------- | :------------------------------------------------------ | :-------- |
| `color` | Line color, such as `'#1e90ff'` | per kind |
| `interiorColor` | Fill color of closed shapes, or `null` for no fill | no fill |
| `opacity` | From `0` (invisible) to `1` (solid) | `1` |
| `strokeWidth` | Line width in points | `1` |
| `borderStyle` | `'solid'` or `'dashed'` | `'solid'` |
| `dashArray` | The pattern a `'dashed'` border draws, such as `[3, 2]` | `[3]` |
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
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:
| Field | What it is |
| :----------- | :-------------------------------------------------- |
| `author` | The display name shown in PDF apps. |
| `createdAt` | When it was created, as an ISO date. |
| `modifiedAt` | When it was last changed. |
| `userId` | The id of the user who owns it. |
| `createdBy` | The id of the user who created it. |
| `modifiedBy` | The id of the user who last changed it. |
| `groupId` | The group it belongs to, when you work with groups. |
The user comes from the `identity` you pass when you open the document; see
[Opening documents](/docs/engine/documents/opening#who-is-working-on-it).
The user comes from the identity in their token; see
[Authentication](/docs/engine/authentication#what-a-token-carries).
## Flags
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.
```ts
await page.annotations.update(annotation.ref, { print: true, locked: true });
```
| Flag | What it does |
| :--------------- | :------------------------------------------------------ |
| `print` | Printed with the page. Off: shown on screen only. |
| `hidden` | Not shown and not printed. |
| `noView` | Not shown on screen (can still print). |
| `locked` | Can't be moved, resized or deleted in PDF apps. |
| `lockedContents` | Its text can't be changed in PDF apps. |
| `readOnly` | Can't be changed at all in PDF apps. |
| `noZoom` | Keeps its size when the page is zoomed (notes, icons). |
| `noRotate` | Stays upright when the page is rotated. |
| `invisible` | Hidden when the app doesn't know the annotation's kind. |
| `toggleNoView` | Flips `noView` when the pointer is over it. |
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
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](/docs/engine/concepts/permissions#annotations).
With CloudPDF, annotations are stored on your server as people make them. Everyone with the
document open gets each other's changes as [events](/docs/engine/concepts/events), and the server
makes sure people only change the annotations they may change.
## More
- [Import & export](/docs/engine/annotations/import-export): copy annotations to another
document, or store them apart from the PDF.
- [Drawing annotations yourself](/docs/engine/annotations/appearances): render annotations as
separate images, bake them into the page, or export them as a PDF.
- [Refs & identity](/docs/engine/concepts/identity): what a `ref` contains, and why you never
build one.
- [Changes & undo](/docs/engine/documents/changes): make several annotation edits as one action,
and undo them.
---
### Content Engine Forms Index (`docs/content/engine/forms/index.mdx`)
---
title: Forms
description: Read a PDF form's fields and values, fill them in, reset them, and move fields and values between documents.
---
# 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.
```ts
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
`list()` returns every field in the document:
```ts
const { fields } = await doc.forms.list();
for (const field of fields) {
console.log(field.name, field.family);
}
```
Every field has these:
| Field | What it is |
| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| `name` | The full name, with the groups it's in: `billing.name`. |
| `family` | `'text'`, `'checkbox'`, `'radio'`, `'combobox'`, `'listbox'`, `'pushbutton'`, `'signature'` or `'unknown'`. |
| `ref` | Its address. Keep it: it's how you fill, reset or change the field. |
| `readOnly` | `true` when PDF apps don't let the user change the value. |
| `required` | `true` when PDF apps ask for a value before the form is submitted. |
| `noExport` | `true` when the field is left out when the form is submitted. |
| `alternateName` | The tooltip PDF apps show, also read by screen readers, or `null`. |
| `groupId` | The group the field belongs to: who fills it in, such as `'buyer'`, or `null`. See [Signers and groups](/docs/engine/forms/groups). |
| `widgets` | Where the field shows on the pages (see [Widgets](#widgets)). |
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](#xfa-forms)).
The list also has `needsAppearances`, `true` when the form asks PDF apps to draw its fields
themselves ([`repair()`](/docs/engine/forms/authoring#repair-a-broken-form) can clear it), and
`calculationOrder` (see [Calculations](#calculations-formatting-and-validation)).
### Values
Each family has its own value fields. Check `family` first, and TypeScript knows which ones the
field has:
```ts
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[]
```
| Family | Its value | Also |
| :----------- | :----------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- |
| `text` | `value`, a string | `defaultValue`, `maxLength` (`null`: no limit), `multiline`, `password`, `comb` |
| `checkbox` | `checked` | `exportValue`: what the form data holds while it's checked |
| `radio` | `value`: the export value of the chosen button, or `'Off'` | `noToggleToOff`, `radiosInUnison` |
| `combobox` | `value` | `options`, `edit` (free text allowed), `defaultValue` |
| `listbox` | `selectedValues`, in option order | `options`, `multiSelect`, `defaultValue` (option values), `topIndex` (the option in its top row) |
| `pushbutton` | none: a button only runs an action | Each widget's `caption`, on its row in `widgets` |
| `signature` | none here: see [Digital signatures](/docs/engine/forms/signatures) | |
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
A field records who created it and who last filled it in, from the identity the document was opened
with:
```ts
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'
```
| Field | What it is |
| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `createdBy`, `createdAt` | Who created the field, and when. `null` for a field another app made. |
| `filledBy`, `filledByName`, `filledAt` | The user whose fill last changed the value, their name, and when. A calculated value counts as filled in by whoever's fill calculated it. `null` after a reset, or an anonymous fill. |
| `importedBy` | Who imported the field with its attribution kept. |
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
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:
```ts
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
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:
```ts
import { toFieldRef } from '@embedpdf/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
`setValue()` takes the field's `ref` and its new value, in the same fields a read returns. What
you read, you can write back:
```ts
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
```
| Family | Value |
| :--------- | :------------------------------------------------------------------------------ |
| `text` | `{ value }`; `null` empties it |
| `checkbox` | `{ checked }` |
| `radio` | `{ value }`: the export value of the button to choose; `'Off'` or `null` clears |
| `combobox` | `{ value }`: an option value; `null` clears |
| `listbox` | `{ selectedValues }`: option values; `[]` clears |
`setValue()` returns the field as it is now:
```ts
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
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
`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:
```ts
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:
```ts
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](#fields-stored-inline);
name one of those yourself and the call fails, the same as a `setValue()` would.
## Move fields and values between documents
`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:
```ts
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](/docs/engine/forms/import-export).
## Events
`setValue()`, `reset()` and `importValues()` fire `forms.valueSet`, one per field that changed.
Each carries what the call returned for that field:
```ts
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.
Each value is saved on the server as you set it. Everyone with the document open gets the event,
with `origin.kind: 'remote'` for other people's changes. See
[Events](/docs/engine/concepts/events).
## Permissions
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](/docs/engine/concepts/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](/docs/engine/forms/signatures#protection-what-signatures-allow).
## More
- [Creating form fields](/docs/engine/forms/authoring): add fields and widgets, change and delete
them, repair a broken form.
- [Import & export](/docs/engine/forms/import-export): copy fields from one document to another,
or fill a form in from a bundle.
- [Digital signatures](/docs/engine/forms/signatures): sign a signature field and check the
signatures in a document.
- [Changes & undo](/docs/engine/documents/changes): fill in several fields as one action, and
undo it.
## Good to know
### Calculations, formatting and validation
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](/docs/engine/forms/authoring#scripts-and-calculations).
The viewer's form plugin runs these scripts and writes their results as one
[change](/docs/engine/documents/changes): `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
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()`](/docs/engine/forms/authoring#repair-a-broken-form) fixes the file.
### A field on several pages
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
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
`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
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.
---
### Content Headless Annotations Index (`docs/content/headless/annotations/index.mdx`)
---
title: Annotations
description: Show the annotations in a PDF, let people draw new ones, and work with them from code.
---
import { Cards, Card } from '@/components/docs/cards';
{/* This page is served at `…/headless//annotations` with NO trailing
slash, so a relative href resolves against `…/headless//`.
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
Register `interactionPlugin()` and `annotationPlugin()`, then put an `` above the
rendered page:
> **Try it:** click the rectangle and drag it, or a corner to resize it. Double-click the text box
> to type in it.
While the annotation layer is on the page, the render layer leaves the annotations out of the page
picture by itself. The annotation layer draws them instead, so they can be selected, moved and
changed.
`interactionPlugin()` is the shared input system. Every tool, from text selection to drawing,
speaks through it; see [Selecting & copying](text/selection) for how it works.
## Let people draw
A **tool** says what a click or a drag on the page creates. Activate one and people can draw:
> **Try it:** drag on the page to draw a rectangle, then pick another tool. **Highlight** marks the
> text you select.
- **`pointer`** selects: click an annotation to select it, then move, resize or turn it.
- **`square`** draws a rectangle: drag, or just click for a default-size one.
- **`ink`** draws freehand.
- **`highlight`** highlights the text you select.
- **`note`** drops a sticky note where you click.
After you draw, the new annotation is selected and the tool stays active, so you can draw another.
You can change both; see [What happens after drawing](annotations/tools#what-happens-after-drawing).
## How it fits together
Everything on these pages is one of five things:
| Thing | What it is | Where you use it |
| :------------- | :--------------------------------------------------------------------------------- | :----------------------------------------- |
| **Annotation** | A record in the PDF: its kind, position, colors and text. | `annotation.list()` |
| **Tool** | What a click or drag creates, with which defaults, cursor and preview. | `annotationPlugin({ tools })` |
| **Layer** | What each page draws: the annotations, the selection box and handles, the preview. | `` |
| **Overlay** | Your own UI attached to an annotation, such as a menu or a hover card. | `` |
| **API** | Reading, creating, changing and deleting annotations, and listening for changes. | `useAnnotation()` |
An annotation here is the same record the engine reads and writes: the same kinds, the same fields
and the same names. What you learn in the [engine's annotation pages](/docs/engine/annotations)
holds here too.
## The built-in tools
| Tool | Makes | How |
| :------------------------------------------------ | :------------------------------------------ | :------------------------------------ |
| `square`, `circle` | A rectangle or an ellipse | Drag, or click for a default size |
| `line` | A line | Drag, or click for a default length |
| `polygon`, `polyline` | A closed or open shape of points | Click each point, double-click to end |
| `ink`, `ink-highlight` | Freehand drawing, or a see-through marker | Draw |
| `free-text`, `free-text-callout` | A text box, or one with a line pointing out | Click or drag, then type |
| `highlight`, `underline`, `strikeout`, `squiggly` | A mark over text | Select text |
| `insert-text`, `replace-text` | A suggested insertion or replacement | Select text |
| `note` | A sticky note | Click |
| `stamp` | An image or a PDF drawing | Click, then pick a file |
| `attachment` | A file pinned to a spot | Click, then pick a file |
| `link` | An area that opens a page or a website | Drag |
Measurement tools (`distance`, `perimeter`, `area`) and redaction (`redact`) are annotation tools
too. Their plugins add the rest of what they need.
You can change any tool, or add your own; see [Tools & defaults](annotations/tools).
## Who wrote it
Every annotation records who made it and who last changed it (`author`, `createdAt`,
`modifiedAt`). You don't set these on the annotation: they come from the user the document was
opened for.
Tell the viewer who the user is, once. Every document it opens uses it:
> **Try it:** draw a rectangle. The list says Dana Smith made it, and when.
`displayName` becomes the `author` other PDF apps show, and `userId` records who owns the
annotation. The same identity decides which annotations count as the user's own when
[permissions](concepts/permissions) say "only their own".
To open one document as someone else, give its entry in `initialDocuments` its own `identity`. It
replaces the viewer's for that document:
```ts
const initialDocuments = [
{ source: contract, identity: { userId: 'bot', displayName: 'Import job' } },
];
```
A document keeps the identity it was opened with. If you change the viewer's `identity`, documents
you open afterwards use the new one.
To change the viewer's identity, for example when someone else signs in, use
`inject(EpdfViewer).updateSettings({ identity })`. Documents you open afterwards use the new one. To
follow your app's login:
```ts
effect(() => viewer.updateSettings({ identity: auth.identity() }));
```
It comes from the identity in the user's token; see
[Authentication](/docs/engine/authentication#what-a-token-carries).
## Settings
Set them when you register the plugin. `snap`, `chrome`, `afterCreate` and `editable` can change
while the app runs, with `annotation.updateSettings({ … })`; `annotation.resetSettings()` goes back to what you
registered, and `useAnnotationSettings()` gives you the current settings.
| Setting | What it does | Page |
| :------------ | :-------------------------------------------------------------------- | :---------------------------------------------------------- |
| `tools` | Change the built-in tools, or add your own | [Tools & defaults](annotations/tools) |
| `afterCreate` | Select a new annotation? Keep the tool active? | [What happens after drawing](annotations/tools#what-happens-after-drawing) |
| `chrome` | The selection's outline, handles and rotation handle, and their colors | [Change the handles](annotations/selecting#change-the-handles) |
| `snap` | Snapping to other annotations and to angles | [Snapping](annotations/selecting#snapping) |
| `editable` | Which annotations people may change by hand: `true`, `false`, or kinds | [What people may change](annotations/selecting#what-people-may-change) |
Every color in `chrome` can also come from CSS, for dark mode or a different look per viewer: see
[Colors & theming](ui/theming).
## Next steps
---
### Content Headless Forms Index (`docs/content/headless/forms/index.mdx`)
---
title: Filling forms
description: Let people fill in PDF forms, read and set values from your code, check required fields, and move form data in and out.
---
# Filling forms
Many PDFs are forms: text boxes, checkboxes, dropdowns, signature fields. Register `formPlugin()` and
put `` in each page, and people can fill them in:
Each field becomes a real HTML control, placed and styled like the field in the PDF: people type in text
boxes, tick checkboxes, pick from lists, and move between fields with Tab. A value is saved into the
document as it's entered, so it's there when the PDF is downloaded, and every PDF app shows it. The
form layer paints the fields as the engine draws them, so while it's on the page, the render layer
leaves them out of the page picture.
## Read the form
`useFormState()` gives you every field, and when a value changes:
`form.fields()` is every field, as a signal: your view updates when a value changes.
Each field has its full `name` (such as `billing.name`), its `family` (`'text'`, `'checkbox'`,
`'radio'`, `'combobox'`, `'listbox'`, `'pushbutton'` or `'signature'`), its value, and a `ref`: its
address for everything else. The fields and their values are the engine's; see
[Forms](/docs/engine/forms#read-the-form) for every family's value.
For one field, such as a total you show in your own UI, use `useFormValue()`:
`toFieldRef(name)` makes a ref from a field's full name, for when you know a field by name.
## Fill in a field
`setValue()` takes the same values a field reads:
```ts
await form.setValue(name.ref, { value: 'Ada Lovelace' }); // text
await form.setValue(agree.ref, { checked: true }); // checkbox
await form.setValue(plan.ref, { value: 'yearly' }); // radio group: the button's export value
await form.setValue(country.ref, { value: 'NL' }); // dropdown: an option's value
await form.setValue(toppings.ref, { selectedValues: ['cheese', 'olives'] }); // list
```
It runs the same checks and scripts as typing does, and resolves with `{ field, status }`: `status`
is `'applied'`, `'unchanged'`, or `'rejected'` when the form's own validation refused the value.
The field shows the new value at once, before the engine answers, and the promise resolves once it
has. What the form's scripts calculate from it goes with it, as one change: one request, and one
step to undo. The field stays editable meanwhile; filling it in again is the next change. A value
the engine refuses goes back to the one the field had.
Your own inputs can fill in fields too. `form.controlOf(ref)` gives you a field as an Angular
`FormControl`: it holds the field's value, and fills in the field when the control changes, with
the same checks and scripts:
To fill many fields at once, such as from your backend, pass them by name:
```ts
await form.importValues({ 'billing.name': 'Ada Lovelace', 'billing.country': 'NL', agree: true });
```
`importValues()` and `setValues()` write every value as one change, with the calculations run once
after them. Each field's own keystroke and validation scripts don't run, as when a script sets a
field's `value` in Acrobat.
## Check required fields
A form marks some fields as required. Check them before you submit or download:
```ts
const { valid, missing } = form.validate();
const widget = !valid && form.getWidget(missing[0].widgets[0]);
if (widget) stage.reveal(widget.page, { rect: widget.rect });
```
`missing` lists the required fields that are empty, in page order, so you can take the user to the
first one. Only the fields the user may fill in count: another signer's are theirs to fill.
## Calculations, formatting and validation
Many forms add up totals, format dates and check values with scripts. With JavaScript on in the
[actions plugin](documents/actions), they run as people type, as in Acrobat:
When a script refuses a value, such as a date in the wrong format, the field keeps its old value,
the box keeps what was typed so it can be corrected, as in Acrobat, and
`onValidationRejected``validationRejected$` tells you why, so you can show a message.
The scripts read the form as the user sees it, values still on their way included, so nothing is
read from the engine for them. Their engine starts when the first field of a form with scripts takes
focus, so the first value doesn't wait for it; a form without scripts never starts it.
## Reset the form
```ts
await form.reset(); // every field the user may fill in, back to its default
await form.reset([name.ref, email.ref]); // some fields
```
## Move form data in and out
For your own backend, plain values are simplest:
```ts
const values = form.exportValues(); // { 'billing.name': 'Ada Lovelace', agree: true, … }
await form.importValues(values);
```
Fields are matched by their full name. A field the form doesn't have, or a value it can't take, is
skipped; the rest still land.
To copy the fields themselves to another document, with their boxes, values and scripts, take
them out as a bundle and import it there. `FormTransfer` turns a bundle into one JSON text to
store, and back:
```ts
const bundle = await form.export(); // every field; or form.export({ fields }), ({ pages })
const text = FormTransfer.stringify(bundle);
const { fields, dropped } = await otherForm.import(await FormTransfer.parse(text));
```
The import adds the fields as one change you can undo. A field whose name the form has already is
left out and listed in `dropped`. By default each field keeps who created and filled it in, which
needs `canRestoreAttribution()`; pass `{ attribution: 'stamp' }` to make them yours. See
[Import & export](/docs/engine/forms/import-export).
## Methods
What `useForm()` gives you for reading and filling. The verbs that change the form itself are
on [Building forms](forms/building#methods).
| Method | What it does |
| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| `get(ref)` | One field, with its value, or `null` when the form has no such field. [Read the form](#read-the-form) |
| `getValue(ref)` | One field's value, in the shape `setValue()` takes, or `null`. In a component, use `useFormValue(ref)`. |
| `getFieldForWidget(widget)` | The field a box belongs to, from the box's ref |
| `getWidget(widget)` | A box's row: its page, its place (`rect`), its look and its state, or `null` when no page shows it |
| `getWidgets(ref)` | Every box a field shows in, as rows in the field's order: a radio group's buttons, or a field repeated on several pages |
| `listWidgets(page)` | Each field box on a page, with its place, its control, its value and whether it can be filled. For drawing the fields yourself. |
| `getWidgetAt(page, point)` | The field box under a point on a page, with its field, or `null` |
| `setValue(ref, value)` | Fills in a field with `{ value }`, `{ checked }` or `{ selectedValues }`, running the form's checks and scripts. Resolves `{ field, status }`. [Fill in a field](#fill-in-a-field) |
| `setValues(entries)` | Fills in several fields, each `{ ref, value }`, as one change with one recalculation; a field you may not fill in, or a value it can't take, fails on its own. Resolves `{ applied, skipped, failed }`. |
| `importValues(values)` | Fills in fields by full name from a plain object, as one change with one recalculation. Resolves `{ applied, skipped, failed }`. [Move form data in and out](#move-form-data-in-and-out) |
| `exportValues()` | Every value, keyed by full name, as a plain object |
| `export(selection?)` | Whole fields with their boxes, values and scripts, as a bundle: every field, or `{ fields }` or `{ pages }`. [Move form data in and out](#move-form-data-in-and-out) |
| `import(bundle, options?)` | Adds a bundle's fields, as one change. Resolves `{ fields, refMap, dropped }`. Needs `canDesign()`. [Move form data in and out](#move-form-data-in-and-out) |
| `reset(refs?)` | Puts back each field's default, for every field the user may fill in or the fields you pass. Resolves `{ fields }`, the fields it changed. [Reset the form](#reset-the-form) |
| `validate()` | Checks the required fields the user may fill in. Returns `{ valid, missing }`, the empty ones in page order. [Check required fields](#check-required-fields) |
| `activateWidget(widget)` | Does what a click on a field box does, such as running a button's action |
| `getSnapshot()` | Everything at once, as the user sees it: what the engine's `list()` returns, with the values still on their way. `fields`, `widgets`, `formKind`, `needsAppearances` and `calculationOrder` |
| `refresh()` | Reads the whole form again, and `onResynced``resynced$` fires. You rarely need it: the plugin follows every change, whoever made it. |
| `canRead()`, `canFill(ref)` | Whether reading the form, and filling in a field, are allowed. [Permissions](#permissions) |
| `getSettings()`, `updateSettings(changes)`, `resetSettings()` | Reads the settings, changes them while the app runs, or goes back to what you registered. In a component, use `useFormSettings()`. [Settings](#settings) |
Every method that returns a promise also takes a `signal` in its options, to cancel it.
## State
| Field | What it is | Read once |
| :-------------- | :---------------------------------------------------------------------------------------------- | :--------------------------------------------------- |
| `fields` | Every field, with its value | `list()`, or `list({ family, page, name })` for some |
| `status` | Whether the form is read: `'idle'`, `'loading'`, `'ready'`, `'forbidden'` or `'error'` | `getStatus()` |
| `formKind` | What the document has: `'none'`, `'acroform'` (a regular PDF form) or `'xfa'` | `getFormKind()` |
| `selectedField` | In design mode, the field of the selected box, or `null`; see [Building forms](forms/building#change-a-fields-settings) | `getSelectedField()` |
For one field, `useFormValue(ref)` only when that field's value changes.
## Settings
Set them when you register the plugin, and change them while the app runs with
`form.updateSettings({ … })`; `form.resetSettings()` goes back to what you registered, and
`useFormSettings()` gives you the current settings.
| Setting | What it does | Default | From CSS |
| :------------------ | :------------------------------------------------------------------------- | :--------------------------- | :----------------------------- |
| `validation` | Run the form's own checks (`'scripts'`), or accept every value (`'none'`) | `'scripts'` | — |
| `focus.color` | The ring around the field being filled in | the viewer's accent | `--epdf-form-focus` |
| `fields.border` | The edge of a field that has no border of its own | the viewer's accent at 55% | `--epdf-form-field-border` |
| `fields.background` | Inside a field that has no background of its own | `'rgb(255 255 255 / 0.92)'` | `--epdf-form-field-background` |
| `fields.color` | The check mark and text of a field that has no color of its own | `'#1f2a44'` | `--epdf-form-field-color` |
| `fillable` | Which fields people fill in by hand: `true`, `false`, or field families | `true` | — |
Scripts need JavaScript on in the actions plugin; without it, `'scripts'` accepts every value too,
and a form with scripts logs a hint once.
`fillable` is for the people using your app. A field it leaves out draws as a read-only field
does, and takes no typing, clicks or picks; your code still fills it in with `setValue()` and
`importValues()`, and `canFill(ref)` doesn't change:
```ts
formPlugin({ fillable: false }); // show the values, take no input
form.updateSettings({ fillable: ['text', 'checkbox'] }); // only these families
form.updateSettings({ fillable: true }); // every field again
```
The families are `'text'`, `'checkbox'`, `'radio'`, `'combobox'`, `'listbox'`, `'pushbutton'` and
`'signature'` (signing a field is filling it in). To stop your code too, leave `doc.forms.fill` out
of the scope (see [Permissions](#permissions)).
The colors are what the viewer draws around fields; a field's own colors are saved in the PDF (see
[Building forms](forms/building)). A CSS variable wins over the setting: see
[Colors & theming](ui/theming).
## Events
| Event | Fires when | Carries |
| :--------------------- | :------------------------------------------------------------------------ | :---------------- |
| `onValueChanged` | A field's value changed | `field`, `origin` |
| `onValidationRejected` | The form's validation refused a value | `field`, `issues` |
| `onResynced` | The whole form was read, as when it opens, after `refresh()` or a repair | `snapshot` |
| `onSettingsChanged` | The settings changed | `settings`, `changed` |
Fields that are added, changed or removed have their own events; see
[Building forms](forms/building#events).
## Permissions
| Permission | What it allows | Check |
| :--------------- | :--------------- | :------------------ |
| `doc.forms.read` | Reading the form | `form.canRead()` |
| `doc.forms.fill` | Filling it in | `form.canFill(ref)` |
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](/docs/engine/forms/groups).
## Good to know
### Forms and annotations
A field's widgets are the form's: the annotation plugin never lists them. With the
[annotation plugin](annotations) registered, the `` and the annotation layer share the page: fields stay fillable with the
`pointer` tool, and become movable boxes in [design mode](forms/building).
### Keyboard
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
On the local engine, the values live in the document in this tab until it's downloaded.
With CloudPDF, each value is stored on your server as it's entered, so a half-filled form survives a
closed tab, and your backend reads the answers without asking the user to download or upload a
file.
Each value is stored on your server as it's entered, so a half-filled form survives a closed tab.
### XFA forms
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](/docs/engine/forms#xfa-forms).
### Signed documents
A signature can lock the whole form, or some fields. Locked fields show their values and can't be
changed; see [Signatures](forms/signatures).
---
### Content Viewer Features Index (`docs/content/viewer/features/index.mdx`)
---
title: All features
description: Everything the viewer can do, how to leave a feature out, who the user is, and where each feature's settings go.
---
# 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:
```js
{ disable: ['forms', 'redaction', 'measurement'] }
```
| Feature | What people can do | Settings |
| :-- | :-- | :-- |
| `annotations` | Highlight, underline and strike out text; draw; add notes, text boxes and callouts | [Annotations](features/annotations) |
| `shapes` | Draw rectangles, circles, lines, arrows and polygons | [Annotations](features/annotations#the-tools) |
| `comments` | Comment on annotations and reply, in a panel with every thread | [Annotations](features/annotations#comments) |
| `stamps` | Place stamps: the standard ones, their own, or images | [Annotations](features/annotations#stamps) |
| `signatures` | Draw, type or upload a signature; sign fields; check signatures | [Forms & signatures](features/forms-and-signatures#signatures) |
| `forms` | Fill in forms; build them in the Form mode | [Forms & signatures](features/forms-and-signatures) |
| `redaction` | Mark text and areas, then remove them from the file for good | [Annotations](features/annotations#redaction) |
| `measurement` | Measure distances, perimeters and areas at the drawing's scale | [Annotations](features/annotations#measurements) |
| `pages` | Rotate, move, insert, duplicate and delete pages in the thumbnails panel, each step undoable | [Panels](customize/panels#organize-pages) |
| `attachments` | See, save, attach and remove files inside the PDF | [Panels](customize/panels#the-attachments) |
| `search` | Find text, with every match highlighted and listed | [`plugins.search`](/docs/headless/text/search#settings) |
| `text` | Select and copy text | [`plugins.selection`](/docs/headless/text/selection#settings) |
| `thumbnails` | A picture of every page, to jump around | [Panels](customize/panels) |
| `outline` | The document's table of contents | [Panels](customize/panels) |
| `documents` | Open other files (with the local engine), download, print, several documents in tabs | [Documents](documents) |
## Leave features out
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](features/turning-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
The user's name becomes the author of the annotations and comments they make:
```js
{ identity: { displayName: 'Ada Lovelace' } }
```
The user's name becomes the author of the annotations and comments they make. On CloudPDF, who the
user is and what they may do come from the document's token, so your server decides.
## Each feature's settings
Every feature is a headless plugin, and `plugins` takes its settings by the plugin's name, exactly
as the plugin's page lists them:
```js
{
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](code/plugins) for every plugin and how to change its settings
while the viewer runs.
## Good to know
### What loads when
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](concepts/how-it-works#what-loads-when)
has the whole order.
---
### Website Src Content Docs Index (`website/src/content/docs/index.mdx`)
---
title: Documentation
description: Choose the ready-made viewer, headless components, or the EmbedPDF Engine directly.
searchable: false
---
---
### Cloudpdf Website Src Content Docs Index (`cloudpdf/website/src/content/docs/index.mdx`)
---
title: Introduction
searchable: false
description: Documentation for CloudPDF — the cloud PDF viewer with collaboration, access control, and secure storage built in.
---
import { DocsLanding } from '@/components/site/docs-landing';
---
### Website Src Content Docs Engine Index (`website/src/content/docs/engine/index.mdx`)
---
title: Engine
description: Open, read, change and save PDF files from JavaScript, with one typed API.
---
{/* Generated from docs/content — edit there, then `pnpm docs:sync`. */}
import { Cards, Card } from '@/components/docs/cards';
# The PDF engine
The EmbedPDF engine opens PDF files in the browser and lets you render their pages, read and
search their text, add annotations, fill forms, edit pages and save the result. It runs PDFium,
the PDF library inside Chrome, in a Web Worker, so your page stays responsive. Nothing is
uploaded: the file never leaves the device.
The ready-made viewer and the headless components are built on this engine. Use it directly
when you want PDF features without a viewer: a thumbnail job, a form filler, an export script.
The CloudPDF engine gives your app a full PDF engine over HTTPS. Your files stay on your
CloudPDF server. The engine renders their pages, reads and searches their text, stores
annotations and form values, and checks every call against the permissions in the user's
token.
The CloudPDF viewer and the headless components are built on this engine. Use it directly when
you want PDF features without a viewer: a thumbnail job, a form filler, an export script.
```ts
import { localEngine } from '@embedpdf/engine';
const engine = localEngine();
const doc = await engine.open({ kind: 'bytes', bytes });
const { pages } = await doc.pages.list();
const image = await doc.page(pages[0].ref).render.image();
```
```ts
import { cloudEngine } from '@cloudpdf/engine';
const engine = cloudEngine();
const doc = await engine.open({ kind: 'token', token: () => fetchDocumentToken(documentId) });
const { pages } = await doc.pages.list();
const image = await doc.page(pages[0].ref).render.image();
```
## What you can do
- **[Render pages](/docs/engine/documents/rendering)** as images, at any size.
- **[Read](/docs/engine/text/extraction), [search](/docs/engine/text/search) and
[select](/docs/engine/text/selection-and-geometry)** the text on a page, and find out where
each character is.
- **[Add and edit annotations](/docs/engine/annotations)**: highlights, notes, shapes, stamps,
measurements. Copy them to another document with
[import & export](/docs/engine/annotations/import-export).
- **[Fill forms](/docs/engine/forms)**, create form fields and
[sign](/docs/engine/forms/signatures) documents.
- **[Change pages](/docs/engine/documents/pages)**: rotate, reorder, delete, insert, merge and
split.
- **[Redact](/docs/engine/documents/redaction)** content for good, and
**[save](/docs/engine/documents/saving)** the result.
- **[Group edits into changes](/docs/engine/documents/changes)** that apply all or none, and undo
or redo any of them.
Every call is async, can be cancelled, and fails with a typed error you can branch on. The same
code runs on the local engine and on the CloudPDF engine: only how you create the engine and
open a file differs.
A few things exist only on the local engine: its fonts, `warmup()`, raw pixels, and saving a
document's layer or to a file. A document opened with `localEngine()` has them. Code that takes
any engine checks first:
```ts
import { isLocalDocument } from '@embedpdf/engine';
if (isLocalDocument(doc)) {
const layer = await doc.downloadLayer();
}
```
`isLocalEngine(engine)` does the same for an engine.
## Local or cloud
This engine runs in the browser: no server, no upload, and it works offline. That makes it the
right choice when the user already has the file, or when the file may not leave their device.
When the file lives on your server, the CloudPDF engine runs the same API there and checks every
call. A user sees the first page as an image, without downloading the whole PDF or the engine
(about 3 MB compressed), and a user who may not download the file never receives it. Your code
stays the same: swap `localEngine()` for `cloudEngine()`.
## Next steps
---
### Website Src Content Docs Headless Index (`website/src/content/docs/headless/index.mdx`)
---
title: Headless
description: Build your own PDF viewer from plugins, components and hooks, in React, Vue, Svelte or Angular.
---
{/* Generated from docs/content — edit there, then `pnpm docs:sync`. */}
import { Cards, Card } from '@/components/docs/cards';
{/* Served at `…/headless/` with NO trailing slash: a relative href
resolves against `…/headless/`, so pages are `quick-start`,
`viewing/stage`, `concepts/how-it-works`. */}
# Build your own PDF viewer
The headless packages give you everything a PDF viewer does, without a look of their own: pages
that scroll and zoom, crisp rendering, text selection and search, annotations, forms and
signatures. You build the interface in , and nothing appears on screen unless you put
it there.
That's a complete viewer: the pages scroll, zoom with a pinch or Ctrl and the wheel, and stay sharp
at every zoom. Everything else is a plugin you add, and a few lines of your own UI.
## Headless or the ready-made Viewer?
EmbedPDF comes in two forms, built on the same engine and plugins:
- **The [Viewer](/docs/viewer)** is finished: a toolbar, sidebars, annotation tools and search,
ready in minutes. You configure it and theme it.
- **Headless** is the parts: you decide what the toolbar looks like, where the search box goes, and
what happens when someone clicks an annotation.
Choose headless when the viewer is part of your product's own interface. You can start with the
Viewer and move to headless later: the plugins and their options are the same.
## How it's put together
A headless viewer has five parts. You meet them on every page:
- **The engine** opens and reads PDF files. It runs in the browser, or on your server with
CloudPDF.
- **``** starts the engine, opens documents, and holds the plugins.
- **Plugins** add one feature each: search, annotations, forms. Register the ones you need; the
rest never reach your bundle.
- **Layers** draw inside each page: the page itself, the text selection, the annotations.
- **Hooks****Composables****Functions****Services** connect your own UI: `useSearch()`
to search, `useSearchState()` to show the results, `useSearchEvent()` to react when something
happens.`inject(EpdfSearch)` gives you the plugin's methods to search,
its values as signals to show the results (`search.hitCount()`), and its events as streams to
react when something happens (`search.completed$`).
[How it works](concepts/how-it-works) explains each in a few minutes.
## Every plugin
Each plugin is one import line. Registering a plugin and importing its components come from the
same place:
| Plugin | What it gives you | Import from |
| :-- | :-- | :-- |
| [Stage](viewing/stage) | Scrolling, zoom, layouts, page navigation | `@embedpdf/react/stage` |
| [Render](viewing/render) | Sharp pages at every zoom, deep-zoom tiles | `@embedpdf/react/render` |
| [Links](viewing/links) | Clickable links to pages and websites | `@embedpdf/react/link` |
| [Selection](text/selection) | Selecting and copying text | `@embedpdf/react/selection` |
| [Search](text/search) | Finding text, and showing every match | `@embedpdf/react/search` |
| [Annotations](annotations) | Highlights, notes, shapes, free text, and your own tools | `@embedpdf/react/annotation` |
| [Stamps](annotations/stamps) | Libraries of stamps, placed by click or by code | `@embedpdf/react/stamp` |
| [Measurements](annotations/measurements) | Distances, perimeters and areas at a real scale | `@embedpdf/react/measurement` |
| [Redaction](annotations/redaction) | Removing content for good | `@embedpdf/react/redaction` |
| [Forms](forms) | Filling and building PDF forms | `@embedpdf/react/form` |
| [Signatures](forms/signatures) | Signing documents and checking signatures | `@embedpdf/react/signature` |
| [Page edit](documents/pages) | Rotating, reordering, inserting and deleting pages | `@embedpdf/react/page-edit` |
| [Metadata](documents/metadata) | A document's title, author and your own fields | `@embedpdf/react/metadata` |
| [Actions](documents/actions) | What a PDF does by itself: buttons, scripts, printing | `@embedpdf/react/actions` |
| [View manager](documents/tabs) | Several documents side by side | `@embedpdf/react/view-manager` |
| [Interaction](ui/tools) | The active tool, cursors and touch | `@embedpdf/react/interaction` |
| [Commands](ui/commands) | Named actions with labels, icons and shortcuts | `@embedpdf/react/commands` |
| [Shell](ui/panels) | Which panels, dialogs and menus are open | `@embedpdf/react/shell` |
| [Translations](ui/translations) | Your UI in the user's language | `@embedpdf/react/i18n` |
## Local or cloud
The same viewer runs on either engine. Only how you create the engine and open a document differs;
every plugin, and component stays the same.
The local engine runs in the browser: no server, no upload, and it works offline. It's the right
choice when the user already has the file, or when the file may not leave their device.
With the CloudPDF engine, the file stays on your server and pages arrive as images, so the first
page shows at once, without downloading the whole PDF or the engine. Every call is checked on the
server, several people can review one document together, and every change is stored as it's made.
Your viewer stays the same: swap `localEngine()` for `cloudEngine()`.
The CloudPDF engine keeps the file on your server. Pages arrive as images, so the first page
shows at once; every call is checked against the user's token; and annotations and form values are
stored as people make them, with everyone who has the document open seeing each other's changes.
## Next steps
---
### Website Src Content Docs Viewer Index (`website/src/content/docs/viewer/index.mdx`)
---
title: Viewer
description: A complete PDF viewer you add with one tag, then make your own with a few lines of config, in plain HTML, React, Vue, Svelte or Angular.
---
{/* Generated from docs/content — edit there, then `pnpm docs:sync`. */}
import { Cards, Card } from '@/components/docs/cards';
{/* Served at `…/viewer/` with NO trailing slash: a relative href
resolves against `…/viewer/`, so pages are `quick-start`,
`customize/layout`, `concepts/how-it-works`. */}
# A complete PDF viewer, ready to embed
The viewer is everything people expect from a PDF app, in one tag: a toolbar, thumbnails, search,
annotations, comments, forms, signatures and stamps. It fits a phone and a wide screen, speaks the
user's language, and works with a keyboard and a screen reader.
That's the whole integration. The rest of these docs are about making it yours.
## Make it yours
Everything you change is a few lines of config, the same in every framework. Start at the top and
stop when it's enough:
| You want to | Change | Page |
| :-- | :-- | :-- |
| Match your brand | Your accent color, fonts, light or dark | [Theming](customize/theming) |
| Leave features out, or make it read-only | `disable: ['forms', 'redaction']`, `readOnly: true` | [Turn features off](features/turning-off) |
| Move or remove buttons | One line per change | [Layout](customize/layout) |
| Put a toolbar at the bottom, on the side, or several | Where each bar goes | [Layout](customize/layout) |
| Add your own button | A command: a label, an icon, what it does | [Buttons & commands](customize/commands) |
| Add your own menu or panel | A list of items, or your component | [Menus](customize/menus), [Panels](customize/panels) |
| Put your own component in the toolbar | Your React, Vue, Svelte or Angular component | [Your own components](customize/components) |
| Control the viewer from your app | The `viewer` object | [The viewer in code](code/viewer) |
You never write layout code for phones, menus that open the right way, or keyboard focus. You say
what goes where, and the viewer takes care of how it behaves. A menu in a bottom toolbar opens
upward; the thumbnails slide up from the bottom on a phone; a button that doesn't fit moves into
the "More" menu.
## The viewer or headless?
EmbedPDF comes in two forms, built on the same engine and the same plugins:
- **The viewer** is finished. You configure it, theme it, and add your own buttons, menus, panels
and components.
- **[Headless](/docs/headless)** is the parts. You build the whole interface yourself, and
nothing appears on screen unless you put it there.
Start with the viewer. Every feature is a [headless plugin](code/plugins) with the same settings,
and inside the viewer your own components can use the headless hooks. If you outgrow the viewer,
what you learned still applies.
## Local or cloud
The viewer runs on the local engine by default: the PDF opens in the browser, with no server and no
upload, and it works offline.
With CloudPDF, the file stays on your server and pages arrive as images, so the first page shows
at once, without downloading the whole PDF or the engine. Every action is checked on the server,
and annotations and comments are shared live between everyone who has the document open. The
viewer and your config stay the same.
## The CloudPDF viewer
The file stays on your server. Pages arrive as images, so the first page shows at once; every
action is checked against the user's token; and annotations, comments and form values are stored
as people make them, with everyone who has the document open seeing each other's changes.
## Next steps
---
### Cloudpdf Website Src Content Docs Api Reference Index (`cloudpdf/website/src/content/docs/api-reference/index.mdx`)
---
title: CloudPDF API reference
description: Complete reference for the CloudPDF server API, with examples for all seven official SDKs.
---
import { Callout } from '@/components/docs/callout';
# CloudPDF API reference
The CloudPDF server API is what your **backend** calls: it gets documents in and
mints the short-lived tokens your viewer opens with. The browser never talks to
this API directly.
Every operation below is generated from the same OpenAPI contract that generates
the official SDKs, so the reference cannot drift from the wire.
The current API and SDK line is a preview. Endpoint pages display the exact canonical version,
and your SDK language is remembered across the whole reference — pick it once below.
## Install
Seven official SDKs, all generated from the contract below. Your choice here is
remembered for every example in the reference.
## Get access
On managed CloudPDF **your account is a tenant** — tenants and deployment
configuration are operated by the platform, so the sections marked
*Self-hosted* below don't apply to you.
Your API key from the [dashboard](https://app.cloudpdf.com) is a **tenant token**: it can manage
documents and mint document tokens under your account, and nothing else.
Use it as the `token` in every example in this reference.
On a self-hosted deployment **you are the operator**. Configure the root
credential on the server:
```sh
CLOUDPDF_API_AUTH_TOKENS=
```
The API token is valid on every surface — including creating the
[tenants](/docs/api-reference/tenants/create) that namespace your
customers' documents. Use it as the `token` in every example, or mint
scoped [tenant tokens](/docs/api-reference/authentication#tenant-tokens)
for your services.
## Getting a document on screen
Three steps, and only the last one runs in a browser.
1. **[Initialize an upload](/docs/api-reference/documents/init)** — request upload
access, transfer the file using the returned instructions, then
[commit the upload](/docs/api-reference/documents/commit).
2. **[Issue a document token](/docs/api-reference/tokens/issue)** — a short-lived JWT
pinned to one document, carrying exactly the capabilities that user should have.
3. **Open it** — hand that token to the viewer or headless components. See
[Engine: getting started](/docs/engine).
Steps 1–2 are the API surface documented here. Step 3 is the client SDK.
## Authentication
Three credentials, and **authority mints only downward**. Each rung is weaker
than the one above it, and only the last one ever reaches a browser.
[How authentication works →](/docs/api-reference/authentication) — minting,
signing modes, revocation, and the full capability tables.
## Resources
---
### Cloudpdf Website Src Content Docs Engine Index (`cloudpdf/website/src/content/docs/engine/index.mdx`)
---
title: Engine
description: Open, read, change and save PDF files from JavaScript, with one typed API.
---
{/* Generated from docs/content — edit there, then `pnpm docs:sync`. */}
import { Cards, Card } from '@/components/docs/cards';
# The PDF engine
The EmbedPDF engine opens PDF files in the browser and lets you render their pages, read and
search their text, add annotations, fill forms, edit pages and save the result. It runs PDFium,
the PDF library inside Chrome, in a Web Worker, so your page stays responsive. Nothing is
uploaded: the file never leaves the device.
The ready-made viewer and the headless components are built on this engine. Use it directly
when you want PDF features without a viewer: a thumbnail job, a form filler, an export script.
The CloudPDF engine gives your app a full PDF engine over HTTPS. Your files stay on your
CloudPDF server. The engine renders their pages, reads and searches their text, stores
annotations and form values, and checks every call against the permissions in the user's
token.
The CloudPDF viewer and the headless components are built on this engine. Use it directly when
you want PDF features without a viewer: a thumbnail job, a form filler, an export script.
```ts
import { localEngine } from '@cloudpdf/engine';
const engine = localEngine();
const doc = await engine.open({ kind: 'bytes', bytes });
const { pages } = await doc.pages.list();
const image = await doc.page(pages[0].ref).render.image();
```
```ts
import { cloudEngine } from '@cloudpdf/engine';
const engine = cloudEngine();
const doc = await engine.open({ kind: 'token', token: () => fetchDocumentToken(documentId) });
const { pages } = await doc.pages.list();
const image = await doc.page(pages[0].ref).render.image();
```
## What you can do
- **[Render pages](/docs/engine/documents/rendering)** as images, at any size.
- **[Read](/docs/engine/text/extraction), [search](/docs/engine/text/search) and
[select](/docs/engine/text/selection-and-geometry)** the text on a page, and find out where
each character is.
- **[Add and edit annotations](/docs/engine/annotations)**: highlights, notes, shapes, stamps,
measurements. Copy them to another document with
[import & export](/docs/engine/annotations/import-export).
- **[Fill forms](/docs/engine/forms)**, create form fields and
[sign](/docs/engine/forms/signatures) documents.
- **[Change pages](/docs/engine/documents/pages)**: rotate, reorder, delete, insert, merge and
split.
- **[Redact](/docs/engine/documents/redaction)** content for good, and
**[save](/docs/engine/documents/saving)** the result.
- **[Group edits into changes](/docs/engine/documents/changes)** that apply all or none, and undo
or redo any of them.
Every call is async, can be cancelled, and fails with a typed error you can branch on. The same
code runs on the local engine and on the CloudPDF engine: only how you create the engine and
open a file differs.
A few things exist only on the local engine: its fonts, `warmup()`, raw pixels, and saving a
document's layer or to a file. A document opened with `localEngine()` has them. Code that takes
any engine checks first:
```ts
import { isLocalDocument } from '@cloudpdf/engine';
if (isLocalDocument(doc)) {
const layer = await doc.downloadLayer();
}
```
`isLocalEngine(engine)` does the same for an engine.
## Local or cloud
This engine runs in the browser: no server, no upload, and it works offline. That makes it the
right choice when the user already has the file, or when the file may not leave their device.
When the file lives on your server, the CloudPDF engine runs the same API there and checks every
call. A user sees the first page as an image, without downloading the whole PDF or the engine
(about 3 MB compressed), and a user who may not download the file never receives it. Your code
stays the same: swap `localEngine()` for `cloudEngine()`.
## Next steps
---
### Cloudpdf Website Src Content Docs Headless Index (`cloudpdf/website/src/content/docs/headless/index.mdx`)
---
title: Headless
description: Build your own PDF viewer from plugins, components and hooks, in React, Vue, Svelte or Angular.
---
{/* Generated from docs/content — edit there, then `pnpm docs:sync`. */}
import { Cards, Card } from '@/components/docs/cards';
{/* Served at `…/headless/` with NO trailing slash: a relative href
resolves against `…/headless/`, so pages are `quick-start`,
`viewing/stage`, `concepts/how-it-works`. */}
# Build your own PDF viewer
The headless packages give you everything a PDF viewer does, without a look of their own: pages
that scroll and zoom, crisp rendering, text selection and search, annotations, forms and
signatures. You build the interface in , and nothing appears on screen unless you put
it there.
That's a complete viewer: the pages scroll, zoom with a pinch or Ctrl and the wheel, and stay sharp
at every zoom. Everything else is a plugin you add, and a few lines of your own UI.
## Headless or the ready-made Viewer?
EmbedPDF comes in two forms, built on the same engine and plugins:
- **The [Viewer](/docs/viewer)** is finished: a toolbar, sidebars, annotation tools and search,
ready in minutes. You configure it and theme it.
- **Headless** is the parts: you decide what the toolbar looks like, where the search box goes, and
what happens when someone clicks an annotation.
Choose headless when the viewer is part of your product's own interface. You can start with the
Viewer and move to headless later: the plugins and their options are the same.
## How it's put together
A headless viewer has five parts. You meet them on every page:
- **The engine** opens and reads PDF files. It runs in the browser, or on your server with
CloudPDF.
- **``** starts the engine, opens documents, and holds the plugins.
- **Plugins** add one feature each: search, annotations, forms. Register the ones you need; the
rest never reach your bundle.
- **Layers** draw inside each page: the page itself, the text selection, the annotations.
- **Hooks****Composables****Functions****Services** connect your own UI: `useSearch()`
to search, `useSearchState()` to show the results, `useSearchEvent()` to react when something
happens.`inject(EpdfSearch)` gives you the plugin's methods to search,
its values as signals to show the results (`search.hitCount()`), and its events as streams to
react when something happens (`search.completed$`).
[How it works](concepts/how-it-works) explains each in a few minutes.
## Every plugin
Each plugin is one import line. Registering a plugin and importing its components come from the
same place:
| Plugin | What it gives you | Import from |
| :-- | :-- | :-- |
| [Stage](viewing/stage) | Scrolling, zoom, layouts, page navigation | `@embedpdf/react/stage` |
| [Render](viewing/render) | Sharp pages at every zoom, deep-zoom tiles | `@embedpdf/react/render` |
| [Links](viewing/links) | Clickable links to pages and websites | `@embedpdf/react/link` |
| [Selection](text/selection) | Selecting and copying text | `@embedpdf/react/selection` |
| [Search](text/search) | Finding text, and showing every match | `@embedpdf/react/search` |
| [Annotations](annotations) | Highlights, notes, shapes, free text, and your own tools | `@embedpdf/react/annotation` |
| [Stamps](annotations/stamps) | Libraries of stamps, placed by click or by code | `@embedpdf/react/stamp` |
| [Measurements](annotations/measurements) | Distances, perimeters and areas at a real scale | `@embedpdf/react/measurement` |
| [Redaction](annotations/redaction) | Removing content for good | `@embedpdf/react/redaction` |
| [Forms](forms) | Filling and building PDF forms | `@embedpdf/react/form` |
| [Signatures](forms/signatures) | Signing documents and checking signatures | `@embedpdf/react/signature` |
| [Page edit](documents/pages) | Rotating, reordering, inserting and deleting pages | `@embedpdf/react/page-edit` |
| [Metadata](documents/metadata) | A document's title, author and your own fields | `@embedpdf/react/metadata` |
| [Actions](documents/actions) | What a PDF does by itself: buttons, scripts, printing | `@embedpdf/react/actions` |
| [View manager](documents/tabs) | Several documents side by side | `@embedpdf/react/view-manager` |
| [Interaction](ui/tools) | The active tool, cursors and touch | `@embedpdf/react/interaction` |
| [Commands](ui/commands) | Named actions with labels, icons and shortcuts | `@embedpdf/react/commands` |
| [Shell](ui/panels) | Which panels, dialogs and menus are open | `@embedpdf/react/shell` |
| [Translations](ui/translations) | Your UI in the user's language | `@embedpdf/react/i18n` |
## Local or cloud
The same viewer runs on either engine. Only how you create the engine and open a document differs;
every plugin, and component stays the same.
The local engine runs in the browser: no server, no upload, and it works offline. It's the right
choice when the user already has the file, or when the file may not leave their device.
With the CloudPDF engine, the file stays on your server and pages arrive as images, so the first
page shows at once, without downloading the whole PDF or the engine. Every call is checked on the
server, several people can review one document together, and every change is stored as it's made.
Your viewer stays the same: swap `localEngine()` for `cloudEngine()`.
The CloudPDF engine keeps the file on your server. Pages arrive as images, so the first page
shows at once; every call is checked against the user's token; and annotations and form values are
stored as people make them, with everyone who has the document open seeing each other's changes.
## Next steps
---
### Cloudpdf Website Src Content Docs React Index (`cloudpdf/website/src/content/docs/react/index.mdx`)
---
title: React
description: Use CloudPDF in your React application.
---
# React
Integrate CloudPDF into your React application. This is a placeholder page;
section content will be added here.
## Getting started
This section will cover installation, the viewer component, and headless usage
in React.
---
### Cloudpdf Website Src Content Docs Svelte Index (`cloudpdf/website/src/content/docs/svelte/index.mdx`)
---
title: Svelte
description: Use CloudPDF in your Svelte application.
---
# Svelte
Integrate CloudPDF into your Svelte application. This is a placeholder page;
section content will be added here.
## Getting started
This section will cover installation, the viewer component, and headless usage
in Svelte.
---
### Cloudpdf Website Src Content Docs Viewer Index (`cloudpdf/website/src/content/docs/viewer/index.mdx`)
---
title: Viewer
description: A complete PDF viewer you add with one tag, then make your own with a few lines of config, in plain HTML, React, Vue, Svelte or Angular.
---
{/* Generated from docs/content — edit there, then `pnpm docs:sync`. */}
import { Cards, Card } from '@/components/docs/cards';
{/* Served at `…/viewer/` with NO trailing slash: a relative href
resolves against `…/viewer/`, so pages are `quick-start`,
`customize/layout`, `concepts/how-it-works`. */}
# A complete PDF viewer, ready to embed
The viewer is everything people expect from a PDF app, in one tag: a toolbar, thumbnails, search,
annotations, comments, forms, signatures and stamps. It fits a phone and a wide screen, speaks the
user's language, and works with a keyboard and a screen reader.
That's the whole integration. The rest of these docs are about making it yours.
## Make it yours
Everything you change is a few lines of config, the same in every framework. Start at the top and
stop when it's enough:
| You want to | Change | Page |
| :-- | :-- | :-- |
| Match your brand | Your accent color, fonts, light or dark | [Theming](customize/theming) |
| Leave features out, or make it read-only | `disable: ['forms', 'redaction']`, `readOnly: true` | [Turn features off](features/turning-off) |
| Move or remove buttons | One line per change | [Layout](customize/layout) |
| Put a toolbar at the bottom, on the side, or several | Where each bar goes | [Layout](customize/layout) |
| Add your own button | A command: a label, an icon, what it does | [Buttons & commands](customize/commands) |
| Add your own menu or panel | A list of items, or your component | [Menus](customize/menus), [Panels](customize/panels) |
| Put your own component in the toolbar | Your React, Vue, Svelte or Angular component | [Your own components](customize/components) |
| Control the viewer from your app | The `viewer` object | [The viewer in code](code/viewer) |
You never write layout code for phones, menus that open the right way, or keyboard focus. You say
what goes where, and the viewer takes care of how it behaves. A menu in a bottom toolbar opens
upward; the thumbnails slide up from the bottom on a phone; a button that doesn't fit moves into
the "More" menu.
## The viewer or headless?
EmbedPDF comes in two forms, built on the same engine and the same plugins:
- **The viewer** is finished. You configure it, theme it, and add your own buttons, menus, panels
and components.
- **[Headless](/docs/headless)** is the parts. You build the whole interface yourself, and
nothing appears on screen unless you put it there.
Start with the viewer. Every feature is a [headless plugin](code/plugins) with the same settings,
and inside the viewer your own components can use the headless hooks. If you outgrow the viewer,
what you learned still applies.
## Local or cloud
The viewer runs on the local engine by default: the PDF opens in the browser, with no server and no
upload, and it works offline.
With CloudPDF, the file stays on your server and pages arrive as images, so the first page shows
at once, without downloading the whole PDF or the engine. Every action is checked on the server,
and annotations and comments are shared live between everyone who has the document open. The
viewer and your config stay the same.
## The CloudPDF viewer
The file stays on your server. Pages arrive as images, so the first page shows at once; every
action is checked against the user's token; and annotations, comments and form values are stored
as people make them, with everyone who has the document open seeing each other's changes.
## Next steps
---
### Cloudpdf Website Src Content Docs Vue Index (`cloudpdf/website/src/content/docs/vue/index.mdx`)
---
title: Vue
description: Use CloudPDF in your Vue application.
---
# Vue
Integrate CloudPDF into your Vue application. This is a placeholder page;
section content will be added here.
## Getting started
This section will cover installation, the viewer component, and headless usage
in Vue.
---
### Website Src Content Docs Engine Annotations Index (`website/src/content/docs/engine/annotations/index.mdx`)
---
title: Annotations
description: List, add, change, reorder and delete annotations, with the fields and styles every kind shares.
---
{/* 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.
```ts
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
Each kind has its own page with an example and its fields:
## List annotations
Every annotation in the document, or the ones on one page:
```ts
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](/docs/engine/concepts/coordinates).
```ts
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](/docs/engine/forms/authoring).
## Fields every annotation has
Besides `subtype`, `rect` and `ref`, every kind has these fields:
| Field | What it is |
| :--------- | :------------------------------------------------------------------------------------------------------- |
| `contents` | A comment, the text PDF apps show for the annotation. |
| `subject` | A short title PDF apps show with the comment, such as `'Question'`. |
| `nm` | A unique name on its page. See [Refs & identity](/docs/engine/concepts/identity). |
| `reply` | The annotation it answers, or `null`. See [Notes & replies](/docs/engine/annotations/notes-and-replies). |
| `popup` | The ref of its popup window, or `null`. See [Popups](/docs/engine/annotations/notes-and-replies#popups). |
| `groupId` | The group it belongs to, when you work with groups. |
Each annotation also has the [flags](#flags) and the fields that say [who wrote it](#who-wrote-it).
## Add an annotation
`create()` takes the kind and its fields, and returns the new annotation:
```ts
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](/docs/engine/annotations/stamps) and
[File attachments](/docs/engine/annotations/file-attachments).
## Change an annotation
`update()` takes the `ref` and only the fields you want to change:
```ts
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:
```ts
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`
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:
```ts
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:
```ts
import { shapeForRect } from '@embedpdf/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](/docs/engine/annotations/shapes#turned-shapes).
## Delete and reorder
```ts
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](/docs/engine/annotations/notes-and-replies#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()`](/docs/engine/forms/authoring#move-and-style-widgets).
## Style
Most kinds share the same style fields:
| Field | What it is | Default |
| :-------------- | :------------------------------------------------------ | :-------- |
| `color` | Line color, such as `'#1e90ff'` | per kind |
| `interiorColor` | Fill color of closed shapes, or `null` for no fill | no fill |
| `opacity` | From `0` (invisible) to `1` (solid) | `1` |
| `strokeWidth` | Line width in points | `1` |
| `borderStyle` | `'solid'` or `'dashed'` | `'solid'` |
| `dashArray` | The pattern a `'dashed'` border draws, such as `[3, 2]` | `[3]` |
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
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:
| Field | What it is |
| :----------- | :-------------------------------------------------- |
| `author` | The display name shown in PDF apps. |
| `createdAt` | When it was created, as an ISO date. |
| `modifiedAt` | When it was last changed. |
| `userId` | The id of the user who owns it. |
| `createdBy` | The id of the user who created it. |
| `modifiedBy` | The id of the user who last changed it. |
| `groupId` | The group it belongs to, when you work with groups. |
The user comes from the `identity` you pass when you open the document; see
[Opening documents](/docs/engine/documents/opening#who-is-working-on-it).
The user comes from the identity in their token; see
[Authentication](/docs/engine/authentication#what-a-token-carries).
## Flags
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.
```ts
await page.annotations.update(annotation.ref, { print: true, locked: true });
```
| Flag | What it does |
| :--------------- | :------------------------------------------------------ |
| `print` | Printed with the page. Off: shown on screen only. |
| `hidden` | Not shown and not printed. |
| `noView` | Not shown on screen (can still print). |
| `locked` | Can't be moved, resized or deleted in PDF apps. |
| `lockedContents` | Its text can't be changed in PDF apps. |
| `readOnly` | Can't be changed at all in PDF apps. |
| `noZoom` | Keeps its size when the page is zoomed (notes, icons). |
| `noRotate` | Stays upright when the page is rotated. |
| `invisible` | Hidden when the app doesn't know the annotation's kind. |
| `toggleNoView` | Flips `noView` when the pointer is over it. |
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
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](/docs/engine/concepts/permissions#annotations).
With CloudPDF, annotations are stored on your server as people make them. Everyone with the
document open gets each other's changes as [events](/docs/engine/concepts/events), and the server
makes sure people only change the annotations they may change.
## More
- [Import & export](/docs/engine/annotations/import-export): copy annotations to another
document, or store them apart from the PDF.
- [Drawing annotations yourself](/docs/engine/annotations/appearances): render annotations as
separate images, bake them into the page, or export them as a PDF.
- [Refs & identity](/docs/engine/concepts/identity): what a `ref` contains, and why you never
build one.
- [Changes & undo](/docs/engine/documents/changes): make several annotation edits as one action,
and undo them.
---
### Website Src Content Docs Engine Forms Index (`website/src/content/docs/engine/forms/index.mdx`)
---
title: Forms
description: Read a PDF form's fields and values, fill them in, reset them, and move fields and values between documents.
---
{/* 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.
```ts
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
`list()` returns every field in the document:
```ts
const { fields } = await doc.forms.list();
for (const field of fields) {
console.log(field.name, field.family);
}
```
Every field has these:
| Field | What it is |
| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| `name` | The full name, with the groups it's in: `billing.name`. |
| `family` | `'text'`, `'checkbox'`, `'radio'`, `'combobox'`, `'listbox'`, `'pushbutton'`, `'signature'` or `'unknown'`. |
| `ref` | Its address. Keep it: it's how you fill, reset or change the field. |
| `readOnly` | `true` when PDF apps don't let the user change the value. |
| `required` | `true` when PDF apps ask for a value before the form is submitted. |
| `noExport` | `true` when the field is left out when the form is submitted. |
| `alternateName` | The tooltip PDF apps show, also read by screen readers, or `null`. |
| `groupId` | The group the field belongs to: who fills it in, such as `'buyer'`, or `null`. See [Signers and groups](/docs/engine/forms/groups). |
| `widgets` | Where the field shows on the pages (see [Widgets](#widgets)). |
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](#xfa-forms)).
The list also has `needsAppearances`, `true` when the form asks PDF apps to draw its fields
themselves ([`repair()`](/docs/engine/forms/authoring#repair-a-broken-form) can clear it), and
`calculationOrder` (see [Calculations](#calculations-formatting-and-validation)).
### Values
Each family has its own value fields. Check `family` first, and TypeScript knows which ones the
field has:
```ts
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[]
```
| Family | Its value | Also |
| :----------- | :----------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- |
| `text` | `value`, a string | `defaultValue`, `maxLength` (`null`: no limit), `multiline`, `password`, `comb` |
| `checkbox` | `checked` | `exportValue`: what the form data holds while it's checked |
| `radio` | `value`: the export value of the chosen button, or `'Off'` | `noToggleToOff`, `radiosInUnison` |
| `combobox` | `value` | `options`, `edit` (free text allowed), `defaultValue` |
| `listbox` | `selectedValues`, in option order | `options`, `multiSelect`, `defaultValue` (option values), `topIndex` (the option in its top row) |
| `pushbutton` | none: a button only runs an action | Each widget's `caption`, on its row in `widgets` |
| `signature` | none here: see [Digital signatures](/docs/engine/forms/signatures) | |
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
A field records who created it and who last filled it in, from the identity the document was opened
with:
```ts
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'
```
| Field | What it is |
| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `createdBy`, `createdAt` | Who created the field, and when. `null` for a field another app made. |
| `filledBy`, `filledByName`, `filledAt` | The user whose fill last changed the value, their name, and when. A calculated value counts as filled in by whoever's fill calculated it. `null` after a reset, or an anonymous fill. |
| `importedBy` | Who imported the field with its attribution kept. |
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
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:
```ts
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
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:
```ts
import { toFieldRef } from '@embedpdf/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
`setValue()` takes the field's `ref` and its new value, in the same fields a read returns. What
you read, you can write back:
```ts
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
```
| Family | Value |
| :--------- | :------------------------------------------------------------------------------ |
| `text` | `{ value }`; `null` empties it |
| `checkbox` | `{ checked }` |
| `radio` | `{ value }`: the export value of the button to choose; `'Off'` or `null` clears |
| `combobox` | `{ value }`: an option value; `null` clears |
| `listbox` | `{ selectedValues }`: option values; `[]` clears |
`setValue()` returns the field as it is now:
```ts
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
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
`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:
```ts
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:
```ts
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](#fields-stored-inline);
name one of those yourself and the call fails, the same as a `setValue()` would.
## Move fields and values between documents
`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:
```ts
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](/docs/engine/forms/import-export).
## Events
`setValue()`, `reset()` and `importValues()` fire `forms.valueSet`, one per field that changed.
Each carries what the call returned for that field:
```ts
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.
Each value is saved on the server as you set it. Everyone with the document open gets the event,
with `origin.kind: 'remote'` for other people's changes. See
[Events](/docs/engine/concepts/events).
## Permissions
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](/docs/engine/concepts/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](/docs/engine/forms/signatures#protection-what-signatures-allow).
## More
- [Creating form fields](/docs/engine/forms/authoring): add fields and widgets, change and delete
them, repair a broken form.
- [Import & export](/docs/engine/forms/import-export): copy fields from one document to another,
or fill a form in from a bundle.
- [Digital signatures](/docs/engine/forms/signatures): sign a signature field and check the
signatures in a document.
- [Changes & undo](/docs/engine/documents/changes): fill in several fields as one action, and
undo it.
## Good to know
### Calculations, formatting and validation
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](/docs/engine/forms/authoring#scripts-and-calculations).
The viewer's form plugin runs these scripts and writes their results as one
[change](/docs/engine/documents/changes): `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
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()`](/docs/engine/forms/authoring#repair-a-broken-form) fixes the file.
### A field on several pages
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
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
`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
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.
---
### Website Src Content Docs Headless Annotations Index (`website/src/content/docs/headless/annotations/index.mdx`)
---
title: Annotations
description: Show the annotations in a PDF, let people draw new ones, and work with them from code.
---
{/* Generated from docs/content — edit there, then `pnpm docs:sync`. */}
import { Cards, Card } from '@/components/docs/cards';
{/* This page is served at `…/headless//annotations` with NO trailing
slash, so a relative href resolves against `…/headless//`.
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
Register `interactionPlugin()` and `annotationPlugin()`, then put an `` above the
rendered page:
> **Try it:** click the rectangle and drag it, or a corner to resize it. Double-click the text box
> to type in it.
While the annotation layer is on the page, the render layer leaves the annotations out of the page
picture by itself. The annotation layer draws them instead, so they can be selected, moved and
changed.
`interactionPlugin()` is the shared input system. Every tool, from text selection to drawing,
speaks through it; see [Selecting & copying](text/selection) for how it works.
## Let people draw
A **tool** says what a click or a drag on the page creates. Activate one and people can draw:
> **Try it:** drag on the page to draw a rectangle, then pick another tool. **Highlight** marks the
> text you select.
- **`pointer`** selects: click an annotation to select it, then move, resize or turn it.
- **`square`** draws a rectangle: drag, or just click for a default-size one.
- **`ink`** draws freehand.
- **`highlight`** highlights the text you select.
- **`note`** drops a sticky note where you click.
After you draw, the new annotation is selected and the tool stays active, so you can draw another.
You can change both; see [What happens after drawing](annotations/tools#what-happens-after-drawing).
## How it fits together
Everything on these pages is one of five things:
| Thing | What it is | Where you use it |
| :------------- | :--------------------------------------------------------------------------------- | :----------------------------------------- |
| **Annotation** | A record in the PDF: its kind, position, colors and text. | `annotation.list()` |
| **Tool** | What a click or drag creates, with which defaults, cursor and preview. | `annotationPlugin({ tools })` |
| **Layer** | What each page draws: the annotations, the selection box and handles, the preview. | `` |
| **Overlay** | Your own UI attached to an annotation, such as a menu or a hover card. | `` |
| **API** | Reading, creating, changing and deleting annotations, and listening for changes. | `useAnnotation()` |
An annotation here is the same record the engine reads and writes: the same kinds, the same fields
and the same names. What you learn in the [engine's annotation pages](/docs/engine/annotations)
holds here too.
## The built-in tools
| Tool | Makes | How |
| :------------------------------------------------ | :------------------------------------------ | :------------------------------------ |
| `square`, `circle` | A rectangle or an ellipse | Drag, or click for a default size |
| `line` | A line | Drag, or click for a default length |
| `polygon`, `polyline` | A closed or open shape of points | Click each point, double-click to end |
| `ink`, `ink-highlight` | Freehand drawing, or a see-through marker | Draw |
| `free-text`, `free-text-callout` | A text box, or one with a line pointing out | Click or drag, then type |
| `highlight`, `underline`, `strikeout`, `squiggly` | A mark over text | Select text |
| `insert-text`, `replace-text` | A suggested insertion or replacement | Select text |
| `note` | A sticky note | Click |
| `stamp` | An image or a PDF drawing | Click, then pick a file |
| `attachment` | A file pinned to a spot | Click, then pick a file |
| `link` | An area that opens a page or a website | Drag |
Measurement tools (`distance`, `perimeter`, `area`) and redaction (`redact`) are annotation tools
too. Their plugins add the rest of what they need.
You can change any tool, or add your own; see [Tools & defaults](annotations/tools).
## Who wrote it
Every annotation records who made it and who last changed it (`author`, `createdAt`,
`modifiedAt`). You don't set these on the annotation: they come from the user the document was
opened for.
Tell the viewer who the user is, once. Every document it opens uses it:
> **Try it:** draw a rectangle. The list says Dana Smith made it, and when.
`displayName` becomes the `author` other PDF apps show, and `userId` records who owns the
annotation. The same identity decides which annotations count as the user's own when
[permissions](concepts/permissions) say "only their own".
To open one document as someone else, give its entry in `initialDocuments` its own `identity`. It
replaces the viewer's for that document:
```ts
const initialDocuments = [
{ source: contract, identity: { userId: 'bot', displayName: 'Import job' } },
];
```
A document keeps the identity it was opened with. If you change the viewer's `identity`, documents
you open afterwards use the new one.
To change the viewer's identity, for example when someone else signs in, use
`inject(EpdfViewer).updateSettings({ identity })`. Documents you open afterwards use the new one. To
follow your app's login:
```ts
effect(() => viewer.updateSettings({ identity: auth.identity() }));
```
It comes from the identity in the user's token; see
[Authentication](/docs/engine/authentication#what-a-token-carries).
## Settings
Set them when you register the plugin. `snap`, `chrome`, `afterCreate` and `editable` can change
while the app runs, with `annotation.updateSettings({ … })`; `annotation.resetSettings()` goes back to what you
registered, and `useAnnotationSettings()` gives you the current settings.
| Setting | What it does | Page |
| :------------ | :-------------------------------------------------------------------- | :---------------------------------------------------------- |
| `tools` | Change the built-in tools, or add your own | [Tools & defaults](annotations/tools) |
| `afterCreate` | Select a new annotation? Keep the tool active? | [What happens after drawing](annotations/tools#what-happens-after-drawing) |
| `chrome` | The selection's outline, handles and rotation handle, and their colors | [Change the handles](annotations/selecting#change-the-handles) |
| `snap` | Snapping to other annotations and to angles | [Snapping](annotations/selecting#snapping) |
| `editable` | Which annotations people may change by hand: `true`, `false`, or kinds | [What people may change](annotations/selecting#what-people-may-change) |
Every color in `chrome` can also come from CSS, for dark mode or a different look per viewer: see
[Colors & theming](ui/theming).
## Next steps
---
### Website Src Content Docs Headless Forms Index (`website/src/content/docs/headless/forms/index.mdx`)
---
title: Filling forms
description: Let people fill in PDF forms, read and set values from your code, check required fields, and move form data in and out.
---
{/* Generated from docs/content — edit there, then `pnpm docs:sync`. */}
# Filling forms
Many PDFs are forms: text boxes, checkboxes, dropdowns, signature fields. Register `formPlugin()` and
put `` in each page, and people can fill them in:
Each field becomes a real HTML control, placed and styled like the field in the PDF: people type in text
boxes, tick checkboxes, pick from lists, and move between fields with Tab. A value is saved into the
document as it's entered, so it's there when the PDF is downloaded, and every PDF app shows it. The
form layer paints the fields as the engine draws them, so while it's on the page, the render layer
leaves them out of the page picture.
## Read the form
`useFormState()` gives you every field, and when a value changes:
`form.fields()` is every field, as a signal: your view updates when a value changes.
Each field has its full `name` (such as `billing.name`), its `family` (`'text'`, `'checkbox'`,
`'radio'`, `'combobox'`, `'listbox'`, `'pushbutton'` or `'signature'`), its value, and a `ref`: its
address for everything else. The fields and their values are the engine's; see
[Forms](/docs/engine/forms#read-the-form) for every family's value.
For one field, such as a total you show in your own UI, use `useFormValue()`:
`toFieldRef(name)` makes a ref from a field's full name, for when you know a field by name.
## Fill in a field
`setValue()` takes the same values a field reads:
```ts
await form.setValue(name.ref, { value: 'Ada Lovelace' }); // text
await form.setValue(agree.ref, { checked: true }); // checkbox
await form.setValue(plan.ref, { value: 'yearly' }); // radio group: the button's export value
await form.setValue(country.ref, { value: 'NL' }); // dropdown: an option's value
await form.setValue(toppings.ref, { selectedValues: ['cheese', 'olives'] }); // list
```
It runs the same checks and scripts as typing does, and resolves with `{ field, status }`: `status`
is `'applied'`, `'unchanged'`, or `'rejected'` when the form's own validation refused the value.
The field shows the new value at once, before the engine answers, and the promise resolves once it
has. What the form's scripts calculate from it goes with it, as one change: one request, and one
step to undo. The field stays editable meanwhile; filling it in again is the next change. A value
the engine refuses goes back to the one the field had.
Your own inputs can fill in fields too. `form.controlOf(ref)` gives you a field as an Angular
`FormControl`: it holds the field's value, and fills in the field when the control changes, with
the same checks and scripts:
To fill many fields at once, such as from your backend, pass them by name:
```ts
await form.importValues({ 'billing.name': 'Ada Lovelace', 'billing.country': 'NL', agree: true });
```
`importValues()` and `setValues()` write every value as one change, with the calculations run once
after them. Each field's own keystroke and validation scripts don't run, as when a script sets a
field's `value` in Acrobat.
## Check required fields
A form marks some fields as required. Check them before you submit or download:
```ts
const { valid, missing } = form.validate();
const widget = !valid && form.getWidget(missing[0].widgets[0]);
if (widget) stage.reveal(widget.page, { rect: widget.rect });
```
`missing` lists the required fields that are empty, in page order, so you can take the user to the
first one. Only the fields the user may fill in count: another signer's are theirs to fill.
## Calculations, formatting and validation
Many forms add up totals, format dates and check values with scripts. With JavaScript on in the
[actions plugin](documents/actions), they run as people type, as in Acrobat:
When a script refuses a value, such as a date in the wrong format, the field keeps its old value,
the box keeps what was typed so it can be corrected, as in Acrobat, and
`onValidationRejected``validationRejected$` tells you why, so you can show a message.
The scripts read the form as the user sees it, values still on their way included, so nothing is
read from the engine for them. Their engine starts when the first field of a form with scripts takes
focus, so the first value doesn't wait for it; a form without scripts never starts it.
## Reset the form
```ts
await form.reset(); // every field the user may fill in, back to its default
await form.reset([name.ref, email.ref]); // some fields
```
## Move form data in and out
For your own backend, plain values are simplest:
```ts
const values = form.exportValues(); // { 'billing.name': 'Ada Lovelace', agree: true, … }
await form.importValues(values);
```
Fields are matched by their full name. A field the form doesn't have, or a value it can't take, is
skipped; the rest still land.
To copy the fields themselves to another document, with their boxes, values and scripts, take
them out as a bundle and import it there. `FormTransfer` turns a bundle into one JSON text to
store, and back:
```ts
const bundle = await form.export(); // every field; or form.export({ fields }), ({ pages })
const text = FormTransfer.stringify(bundle);
const { fields, dropped } = await otherForm.import(await FormTransfer.parse(text));
```
The import adds the fields as one change you can undo. A field whose name the form has already is
left out and listed in `dropped`. By default each field keeps who created and filled it in, which
needs `canRestoreAttribution()`; pass `{ attribution: 'stamp' }` to make them yours. See
[Import & export](/docs/engine/forms/import-export).
## Methods
What `useForm()` gives you for reading and filling. The verbs that change the form itself are
on [Building forms](forms/building#methods).
| Method | What it does |
| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| `get(ref)` | One field, with its value, or `null` when the form has no such field. [Read the form](#read-the-form) |
| `getValue(ref)` | One field's value, in the shape `setValue()` takes, or `null`. In a component, use `useFormValue(ref)`. |
| `getFieldForWidget(widget)` | The field a box belongs to, from the box's ref |
| `getWidget(widget)` | A box's row: its page, its place (`rect`), its look and its state, or `null` when no page shows it |
| `getWidgets(ref)` | Every box a field shows in, as rows in the field's order: a radio group's buttons, or a field repeated on several pages |
| `listWidgets(page)` | Each field box on a page, with its place, its control, its value and whether it can be filled. For drawing the fields yourself. |
| `getWidgetAt(page, point)` | The field box under a point on a page, with its field, or `null` |
| `setValue(ref, value)` | Fills in a field with `{ value }`, `{ checked }` or `{ selectedValues }`, running the form's checks and scripts. Resolves `{ field, status }`. [Fill in a field](#fill-in-a-field) |
| `setValues(entries)` | Fills in several fields, each `{ ref, value }`, as one change with one recalculation; a field you may not fill in, or a value it can't take, fails on its own. Resolves `{ applied, skipped, failed }`. |
| `importValues(values)` | Fills in fields by full name from a plain object, as one change with one recalculation. Resolves `{ applied, skipped, failed }`. [Move form data in and out](#move-form-data-in-and-out) |
| `exportValues()` | Every value, keyed by full name, as a plain object |
| `export(selection?)` | Whole fields with their boxes, values and scripts, as a bundle: every field, or `{ fields }` or `{ pages }`. [Move form data in and out](#move-form-data-in-and-out) |
| `import(bundle, options?)` | Adds a bundle's fields, as one change. Resolves `{ fields, refMap, dropped }`. Needs `canDesign()`. [Move form data in and out](#move-form-data-in-and-out) |
| `reset(refs?)` | Puts back each field's default, for every field the user may fill in or the fields you pass. Resolves `{ fields }`, the fields it changed. [Reset the form](#reset-the-form) |
| `validate()` | Checks the required fields the user may fill in. Returns `{ valid, missing }`, the empty ones in page order. [Check required fields](#check-required-fields) |
| `activateWidget(widget)` | Does what a click on a field box does, such as running a button's action |
| `getSnapshot()` | Everything at once, as the user sees it: what the engine's `list()` returns, with the values still on their way. `fields`, `widgets`, `formKind`, `needsAppearances` and `calculationOrder` |
| `refresh()` | Reads the whole form again, and `onResynced``resynced$` fires. You rarely need it: the plugin follows every change, whoever made it. |
| `canRead()`, `canFill(ref)` | Whether reading the form, and filling in a field, are allowed. [Permissions](#permissions) |
| `getSettings()`, `updateSettings(changes)`, `resetSettings()` | Reads the settings, changes them while the app runs, or goes back to what you registered. In a component, use `useFormSettings()`. [Settings](#settings) |
Every method that returns a promise also takes a `signal` in its options, to cancel it.
## State
| Field | What it is | Read once |
| :-------------- | :---------------------------------------------------------------------------------------------- | :--------------------------------------------------- |
| `fields` | Every field, with its value | `list()`, or `list({ family, page, name })` for some |
| `status` | Whether the form is read: `'idle'`, `'loading'`, `'ready'`, `'forbidden'` or `'error'` | `getStatus()` |
| `formKind` | What the document has: `'none'`, `'acroform'` (a regular PDF form) or `'xfa'` | `getFormKind()` |
| `selectedField` | In design mode, the field of the selected box, or `null`; see [Building forms](forms/building#change-a-fields-settings) | `getSelectedField()` |
For one field, `useFormValue(ref)` only when that field's value changes.
## Settings
Set them when you register the plugin, and change them while the app runs with
`form.updateSettings({ … })`; `form.resetSettings()` goes back to what you registered, and
`useFormSettings()` gives you the current settings.
| Setting | What it does | Default | From CSS |
| :------------------ | :------------------------------------------------------------------------- | :--------------------------- | :----------------------------- |
| `validation` | Run the form's own checks (`'scripts'`), or accept every value (`'none'`) | `'scripts'` | — |
| `focus.color` | The ring around the field being filled in | the viewer's accent | `--epdf-form-focus` |
| `fields.border` | The edge of a field that has no border of its own | the viewer's accent at 55% | `--epdf-form-field-border` |
| `fields.background` | Inside a field that has no background of its own | `'rgb(255 255 255 / 0.92)'` | `--epdf-form-field-background` |
| `fields.color` | The check mark and text of a field that has no color of its own | `'#1f2a44'` | `--epdf-form-field-color` |
| `fillable` | Which fields people fill in by hand: `true`, `false`, or field families | `true` | — |
Scripts need JavaScript on in the actions plugin; without it, `'scripts'` accepts every value too,
and a form with scripts logs a hint once.
`fillable` is for the people using your app. A field it leaves out draws as a read-only field
does, and takes no typing, clicks or picks; your code still fills it in with `setValue()` and
`importValues()`, and `canFill(ref)` doesn't change:
```ts
formPlugin({ fillable: false }); // show the values, take no input
form.updateSettings({ fillable: ['text', 'checkbox'] }); // only these families
form.updateSettings({ fillable: true }); // every field again
```
The families are `'text'`, `'checkbox'`, `'radio'`, `'combobox'`, `'listbox'`, `'pushbutton'` and
`'signature'` (signing a field is filling it in). To stop your code too, leave `doc.forms.fill` out
of the scope (see [Permissions](#permissions)).
The colors are what the viewer draws around fields; a field's own colors are saved in the PDF (see
[Building forms](forms/building)). A CSS variable wins over the setting: see
[Colors & theming](ui/theming).
## Events
| Event | Fires when | Carries |
| :--------------------- | :------------------------------------------------------------------------ | :---------------- |
| `onValueChanged` | A field's value changed | `field`, `origin` |
| `onValidationRejected` | The form's validation refused a value | `field`, `issues` |
| `onResynced` | The whole form was read, as when it opens, after `refresh()` or a repair | `snapshot` |
| `onSettingsChanged` | The settings changed | `settings`, `changed` |
Fields that are added, changed or removed have their own events; see
[Building forms](forms/building#events).
## Permissions
| Permission | What it allows | Check |
| :--------------- | :--------------- | :------------------ |
| `doc.forms.read` | Reading the form | `form.canRead()` |
| `doc.forms.fill` | Filling it in | `form.canFill(ref)` |
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](/docs/engine/forms/groups).
## Good to know
### Forms and annotations
A field's widgets are the form's: the annotation plugin never lists them. With the
[annotation plugin](annotations) registered, the `` and the annotation layer share the page: fields stay fillable with the
`pointer` tool, and become movable boxes in [design mode](forms/building).
### Keyboard
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
On the local engine, the values live in the document in this tab until it's downloaded.
With CloudPDF, each value is stored on your server as it's entered, so a half-filled form survives a
closed tab, and your backend reads the answers without asking the user to download or upload a
file.
Each value is stored on your server as it's entered, so a half-filled form survives a closed tab.
### XFA forms
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](/docs/engine/forms#xfa-forms).
### Signed documents
A signature can lock the whole form, or some fields. Locked fields show their values and can't be
changed; see [Signatures](forms/signatures).
---
### Website Src Content Docs Viewer Features Index (`website/src/content/docs/viewer/features/index.mdx`)
---
title: All features
description: Everything the viewer can do, how to leave a feature out, who the user is, and where each feature's settings go.
---
{/* 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:
```js
{ disable: ['forms', 'redaction', 'measurement'] }
```
| Feature | What people can do | Settings |
| :-- | :-- | :-- |
| `annotations` | Highlight, underline and strike out text; draw; add notes, text boxes and callouts | [Annotations](features/annotations) |
| `shapes` | Draw rectangles, circles, lines, arrows and polygons | [Annotations](features/annotations#the-tools) |
| `comments` | Comment on annotations and reply, in a panel with every thread | [Annotations](features/annotations#comments) |
| `stamps` | Place stamps: the standard ones, their own, or images | [Annotations](features/annotations#stamps) |
| `signatures` | Draw, type or upload a signature; sign fields; check signatures | [Forms & signatures](features/forms-and-signatures#signatures) |
| `forms` | Fill in forms; build them in the Form mode | [Forms & signatures](features/forms-and-signatures) |
| `redaction` | Mark text and areas, then remove them from the file for good | [Annotations](features/annotations#redaction) |
| `measurement` | Measure distances, perimeters and areas at the drawing's scale | [Annotations](features/annotations#measurements) |
| `pages` | Rotate, move, insert, duplicate and delete pages in the thumbnails panel, each step undoable | [Panels](customize/panels#organize-pages) |
| `attachments` | See, save, attach and remove files inside the PDF | [Panels](customize/panels#the-attachments) |
| `search` | Find text, with every match highlighted and listed | [`plugins.search`](/docs/headless/text/search#settings) |
| `text` | Select and copy text | [`plugins.selection`](/docs/headless/text/selection#settings) |
| `thumbnails` | A picture of every page, to jump around | [Panels](customize/panels) |
| `outline` | The document's table of contents | [Panels](customize/panels) |
| `documents` | Open other files (with the local engine), download, print, several documents in tabs | [Documents](documents) |
## Leave features out
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](features/turning-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
The user's name becomes the author of the annotations and comments they make:
```js
{ identity: { displayName: 'Ada Lovelace' } }
```
The user's name becomes the author of the annotations and comments they make. On CloudPDF, who the
user is and what they may do come from the document's token, so your server decides.
## Each feature's settings
Every feature is a headless plugin, and `plugins` takes its settings by the plugin's name, exactly
as the plugin's page lists them:
```js
{
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](code/plugins) for every plugin and how to change its settings
while the viewer runs.
## Good to know
### What loads when
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](concepts/how-it-works#what-loads-when)
has the whole order.
---
### Cloudpdf Website Src Content Docs Engine Annotations Index (`cloudpdf/website/src/content/docs/engine/annotations/index.mdx`)
---
title: Annotations
description: List, add, change, reorder and delete annotations, with the fields and styles every kind shares.
---
{/* 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.
```ts
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
Each kind has its own page with an example and its fields:
## List annotations
Every annotation in the document, or the ones on one page:
```ts
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](/docs/engine/concepts/coordinates).
```ts
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](/docs/engine/forms/authoring).
## Fields every annotation has
Besides `subtype`, `rect` and `ref`, every kind has these fields:
| Field | What it is |
| :--------- | :------------------------------------------------------------------------------------------------------- |
| `contents` | A comment, the text PDF apps show for the annotation. |
| `subject` | A short title PDF apps show with the comment, such as `'Question'`. |
| `nm` | A unique name on its page. See [Refs & identity](/docs/engine/concepts/identity). |
| `reply` | The annotation it answers, or `null`. See [Notes & replies](/docs/engine/annotations/notes-and-replies). |
| `popup` | The ref of its popup window, or `null`. See [Popups](/docs/engine/annotations/notes-and-replies#popups). |
| `groupId` | The group it belongs to, when you work with groups. |
Each annotation also has the [flags](#flags) and the fields that say [who wrote it](#who-wrote-it).
## Add an annotation
`create()` takes the kind and its fields, and returns the new annotation:
```ts
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](/docs/engine/annotations/stamps) and
[File attachments](/docs/engine/annotations/file-attachments).
## Change an annotation
`update()` takes the `ref` and only the fields you want to change:
```ts
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:
```ts
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`
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:
```ts
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:
```ts
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](/docs/engine/annotations/shapes#turned-shapes).
## Delete and reorder
```ts
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](/docs/engine/annotations/notes-and-replies#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()`](/docs/engine/forms/authoring#move-and-style-widgets).
## Style
Most kinds share the same style fields:
| Field | What it is | Default |
| :-------------- | :------------------------------------------------------ | :-------- |
| `color` | Line color, such as `'#1e90ff'` | per kind |
| `interiorColor` | Fill color of closed shapes, or `null` for no fill | no fill |
| `opacity` | From `0` (invisible) to `1` (solid) | `1` |
| `strokeWidth` | Line width in points | `1` |
| `borderStyle` | `'solid'` or `'dashed'` | `'solid'` |
| `dashArray` | The pattern a `'dashed'` border draws, such as `[3, 2]` | `[3]` |
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
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:
| Field | What it is |
| :----------- | :-------------------------------------------------- |
| `author` | The display name shown in PDF apps. |
| `createdAt` | When it was created, as an ISO date. |
| `modifiedAt` | When it was last changed. |
| `userId` | The id of the user who owns it. |
| `createdBy` | The id of the user who created it. |
| `modifiedBy` | The id of the user who last changed it. |
| `groupId` | The group it belongs to, when you work with groups. |
The user comes from the `identity` you pass when you open the document; see
[Opening documents](/docs/engine/documents/opening#who-is-working-on-it).
The user comes from the identity in their token; see
[Authentication](/docs/engine/authentication#what-a-token-carries).
## Flags
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.
```ts
await page.annotations.update(annotation.ref, { print: true, locked: true });
```
| Flag | What it does |
| :--------------- | :------------------------------------------------------ |
| `print` | Printed with the page. Off: shown on screen only. |
| `hidden` | Not shown and not printed. |
| `noView` | Not shown on screen (can still print). |
| `locked` | Can't be moved, resized or deleted in PDF apps. |
| `lockedContents` | Its text can't be changed in PDF apps. |
| `readOnly` | Can't be changed at all in PDF apps. |
| `noZoom` | Keeps its size when the page is zoomed (notes, icons). |
| `noRotate` | Stays upright when the page is rotated. |
| `invisible` | Hidden when the app doesn't know the annotation's kind. |
| `toggleNoView` | Flips `noView` when the pointer is over it. |
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
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](/docs/engine/concepts/permissions#annotations).
With CloudPDF, annotations are stored on your server as people make them. Everyone with the
document open gets each other's changes as [events](/docs/engine/concepts/events), and the server
makes sure people only change the annotations they may change.
## More
- [Import & export](/docs/engine/annotations/import-export): copy annotations to another
document, or store them apart from the PDF.
- [Drawing annotations yourself](/docs/engine/annotations/appearances): render annotations as
separate images, bake them into the page, or export them as a PDF.
- [Refs & identity](/docs/engine/concepts/identity): what a `ref` contains, and why you never
build one.
- [Changes & undo](/docs/engine/documents/changes): 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`)
---
title: Forms
description: Read a PDF form's fields and values, fill them in, reset them, and move fields and values between documents.
---
{/* 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.
```ts
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
`list()` returns every field in the document:
```ts
const { fields } = await doc.forms.list();
for (const field of fields) {
console.log(field.name, field.family);
}
```
Every field has these:
| Field | What it is |
| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| `name` | The full name, with the groups it's in: `billing.name`. |
| `family` | `'text'`, `'checkbox'`, `'radio'`, `'combobox'`, `'listbox'`, `'pushbutton'`, `'signature'` or `'unknown'`. |
| `ref` | Its address. Keep it: it's how you fill, reset or change the field. |
| `readOnly` | `true` when PDF apps don't let the user change the value. |
| `required` | `true` when PDF apps ask for a value before the form is submitted. |
| `noExport` | `true` when the field is left out when the form is submitted. |
| `alternateName` | The tooltip PDF apps show, also read by screen readers, or `null`. |
| `groupId` | The group the field belongs to: who fills it in, such as `'buyer'`, or `null`. See [Signers and groups](/docs/engine/forms/groups). |
| `widgets` | Where the field shows on the pages (see [Widgets](#widgets)). |
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](#xfa-forms)).
The list also has `needsAppearances`, `true` when the form asks PDF apps to draw its fields
themselves ([`repair()`](/docs/engine/forms/authoring#repair-a-broken-form) can clear it), and
`calculationOrder` (see [Calculations](#calculations-formatting-and-validation)).
### Values
Each family has its own value fields. Check `family` first, and TypeScript knows which ones the
field has:
```ts
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[]
```
| Family | Its value | Also |
| :----------- | :----------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- |
| `text` | `value`, a string | `defaultValue`, `maxLength` (`null`: no limit), `multiline`, `password`, `comb` |
| `checkbox` | `checked` | `exportValue`: what the form data holds while it's checked |
| `radio` | `value`: the export value of the chosen button, or `'Off'` | `noToggleToOff`, `radiosInUnison` |
| `combobox` | `value` | `options`, `edit` (free text allowed), `defaultValue` |
| `listbox` | `selectedValues`, in option order | `options`, `multiSelect`, `defaultValue` (option values), `topIndex` (the option in its top row) |
| `pushbutton` | none: a button only runs an action | Each widget's `caption`, on its row in `widgets` |
| `signature` | none here: see [Digital signatures](/docs/engine/forms/signatures) | |
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
A field records who created it and who last filled it in, from the identity the document was opened
with:
```ts
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'
```
| Field | What it is |
| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `createdBy`, `createdAt` | Who created the field, and when. `null` for a field another app made. |
| `filledBy`, `filledByName`, `filledAt` | The user whose fill last changed the value, their name, and when. A calculated value counts as filled in by whoever's fill calculated it. `null` after a reset, or an anonymous fill. |
| `importedBy` | Who imported the field with its attribution kept. |
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
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:
```ts
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
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:
```ts
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
`setValue()` takes the field's `ref` and its new value, in the same fields a read returns. What
you read, you can write back:
```ts
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
```
| Family | Value |
| :--------- | :------------------------------------------------------------------------------ |
| `text` | `{ value }`; `null` empties it |
| `checkbox` | `{ checked }` |
| `radio` | `{ value }`: the export value of the button to choose; `'Off'` or `null` clears |
| `combobox` | `{ value }`: an option value; `null` clears |
| `listbox` | `{ selectedValues }`: option values; `[]` clears |
`setValue()` returns the field as it is now:
```ts
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
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
`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:
```ts
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:
```ts
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](#fields-stored-inline);
name one of those yourself and the call fails, the same as a `setValue()` would.
## Move fields and values between documents
`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:
```ts
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](/docs/engine/forms/import-export).
## Events
`setValue()`, `reset()` and `importValues()` fire `forms.valueSet`, one per field that changed.
Each carries what the call returned for that field:
```ts
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.
Each value is saved on the server as you set it. Everyone with the document open gets the event,
with `origin.kind: 'remote'` for other people's changes. See
[Events](/docs/engine/concepts/events).
## Permissions
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](/docs/engine/concepts/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](/docs/engine/forms/signatures#protection-what-signatures-allow).
## More
- [Creating form fields](/docs/engine/forms/authoring): add fields and widgets, change and delete
them, repair a broken form.
- [Import & export](/docs/engine/forms/import-export): copy fields from one document to another,
or fill a form in from a bundle.
- [Digital signatures](/docs/engine/forms/signatures): sign a signature field and check the
signatures in a document.
- [Changes & undo](/docs/engine/documents/changes): fill in several fields as one action, and
undo it.
## Good to know
### Calculations, formatting and validation
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](/docs/engine/forms/authoring#scripts-and-calculations).
The viewer's form plugin runs these scripts and writes their results as one
[change](/docs/engine/documents/changes): `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
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()`](/docs/engine/forms/authoring#repair-a-broken-form) fixes the file.
### A field on several pages
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
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
`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
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`)
---
title: Annotations
description: Show the annotations in a PDF, let people draw new ones, and work with them from code.
---
{/* Generated from docs/content — edit there, then `pnpm docs:sync`. */}
import { Cards, Card } from '@/components/docs/cards';
{/* This page is served at `…/headless//annotations` with NO trailing
slash, so a relative href resolves against `…/headless//`.
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
Register `interactionPlugin()` and `annotationPlugin()`, then put an `` above the
rendered page:
> **Try it:** click the rectangle and drag it, or a corner to resize it. Double-click the text box
> to type in it.
While the annotation layer is on the page, the render layer leaves the annotations out of the page
picture by itself. The annotation layer draws them instead, so they can be selected, moved and
changed.
`interactionPlugin()` is the shared input system. Every tool, from text selection to drawing,
speaks through it; see [Selecting & copying](text/selection) for how it works.
## Let people draw
A **tool** says what a click or a drag on the page creates. Activate one and people can draw:
> **Try it:** drag on the page to draw a rectangle, then pick another tool. **Highlight** marks the
> text you select.
- **`pointer`** selects: click an annotation to select it, then move, resize or turn it.
- **`square`** draws a rectangle: drag, or just click for a default-size one.
- **`ink`** draws freehand.
- **`highlight`** highlights the text you select.
- **`note`** drops a sticky note where you click.
After you draw, the new annotation is selected and the tool stays active, so you can draw another.
You can change both; see [What happens after drawing](annotations/tools#what-happens-after-drawing).
## How it fits together
Everything on these pages is one of five things:
| Thing | What it is | Where you use it |
| :------------- | :--------------------------------------------------------------------------------- | :----------------------------------------- |
| **Annotation** | A record in the PDF: its kind, position, colors and text. | `annotation.list()` |
| **Tool** | What a click or drag creates, with which defaults, cursor and preview. | `annotationPlugin({ tools })` |
| **Layer** | What each page draws: the annotations, the selection box and handles, the preview. | `` |
| **Overlay** | Your own UI attached to an annotation, such as a menu or a hover card. | `` |
| **API** | Reading, creating, changing and deleting annotations, and listening for changes. | `useAnnotation()` |
An annotation here is the same record the engine reads and writes: the same kinds, the same fields
and the same names. What you learn in the [engine's annotation pages](/docs/engine/annotations)
holds here too.
## The built-in tools
| Tool | Makes | How |
| :------------------------------------------------ | :------------------------------------------ | :------------------------------------ |
| `square`, `circle` | A rectangle or an ellipse | Drag, or click for a default size |
| `line` | A line | Drag, or click for a default length |
| `polygon`, `polyline` | A closed or open shape of points | Click each point, double-click to end |
| `ink`, `ink-highlight` | Freehand drawing, or a see-through marker | Draw |
| `free-text`, `free-text-callout` | A text box, or one with a line pointing out | Click or drag, then type |
| `highlight`, `underline`, `strikeout`, `squiggly` | A mark over text | Select text |
| `insert-text`, `replace-text` | A suggested insertion or replacement | Select text |
| `note` | A sticky note | Click |
| `stamp` | An image or a PDF drawing | Click, then pick a file |
| `attachment` | A file pinned to a spot | Click, then pick a file |
| `link` | An area that opens a page or a website | Drag |
Measurement tools (`distance`, `perimeter`, `area`) and redaction (`redact`) are annotation tools
too. Their plugins add the rest of what they need.
You can change any tool, or add your own; see [Tools & defaults](annotations/tools).
## Who wrote it
Every annotation records who made it and who last changed it (`author`, `createdAt`,
`modifiedAt`). You don't set these on the annotation: they come from the user the document was
opened for.
Tell the viewer who the user is, once. Every document it opens uses it:
> **Try it:** draw a rectangle. The list says Dana Smith made it, and when.
`displayName` becomes the `author` other PDF apps show, and `userId` records who owns the
annotation. The same identity decides which annotations count as the user's own when
[permissions](concepts/permissions) say "only their own".
To open one document as someone else, give its entry in `initialDocuments` its own `identity`. It
replaces the viewer's for that document:
```ts
const initialDocuments = [
{ source: contract, identity: { userId: 'bot', displayName: 'Import job' } },
];
```
A document keeps the identity it was opened with. If you change the viewer's `identity`, documents
you open afterwards use the new one.
To change the viewer's identity, for example when someone else signs in, use
`inject(EpdfViewer).updateSettings({ identity })`. Documents you open afterwards use the new one. To
follow your app's login:
```ts
effect(() => viewer.updateSettings({ identity: auth.identity() }));
```
It comes from the identity in the user's token; see
[Authentication](/docs/engine/authentication#what-a-token-carries).
## Settings
Set them when you register the plugin. `snap`, `chrome`, `afterCreate` and `editable` can change
while the app runs, with `annotation.updateSettings({ … })`; `annotation.resetSettings()` goes back to what you
registered, and `useAnnotationSettings()` gives you the current settings.
| Setting | What it does | Page |
| :------------ | :-------------------------------------------------------------------- | :---------------------------------------------------------- |
| `tools` | Change the built-in tools, or add your own | [Tools & defaults](annotations/tools) |
| `afterCreate` | Select a new annotation? Keep the tool active? | [What happens after drawing](annotations/tools#what-happens-after-drawing) |
| `chrome` | The selection's outline, handles and rotation handle, and their colors | [Change the handles](annotations/selecting#change-the-handles) |
| `snap` | Snapping to other annotations and to angles | [Snapping](annotations/selecting#snapping) |
| `editable` | Which annotations people may change by hand: `true`, `false`, or kinds | [What people may change](annotations/selecting#what-people-may-change) |
Every color in `chrome` can also come from CSS, for dark mode or a different look per viewer: see
[Colors & theming](ui/theming).
## Next steps
---
### Cloudpdf Website Src Content Docs Headless Forms Index (`cloudpdf/website/src/content/docs/headless/forms/index.mdx`)
---
title: Filling forms
description: Let people fill in PDF forms, read and set values from your code, check required fields, and move form data in and out.
---
{/* Generated from docs/content — edit there, then `pnpm docs:sync`. */}
# Filling forms
Many PDFs are forms: text boxes, checkboxes, dropdowns, signature fields. Register `formPlugin()` and
put `` in each page, and people can fill them in:
Each field becomes a real HTML control, placed and styled like the field in the PDF: people type in text
boxes, tick checkboxes, pick from lists, and move between fields with Tab. A value is saved into the
document as it's entered, so it's there when the PDF is downloaded, and every PDF app shows it. The
form layer paints the fields as the engine draws them, so while it's on the page, the render layer
leaves them out of the page picture.
## Read the form
`useFormState()` gives you every field, and when a value changes:
`form.fields()` is every field, as a signal: your view updates when a value changes.
Each field has its full `name` (such as `billing.name`), its `family` (`'text'`, `'checkbox'`,
`'radio'`, `'combobox'`, `'listbox'`, `'pushbutton'` or `'signature'`), its value, and a `ref`: its
address for everything else. The fields and their values are the engine's; see
[Forms](/docs/engine/forms#read-the-form) for every family's value.
For one field, such as a total you show in your own UI, use `useFormValue()`:
`toFieldRef(name)` makes a ref from a field's full name, for when you know a field by name.
## Fill in a field
`setValue()` takes the same values a field reads:
```ts
await form.setValue(name.ref, { value: 'Ada Lovelace' }); // text
await form.setValue(agree.ref, { checked: true }); // checkbox
await form.setValue(plan.ref, { value: 'yearly' }); // radio group: the button's export value
await form.setValue(country.ref, { value: 'NL' }); // dropdown: an option's value
await form.setValue(toppings.ref, { selectedValues: ['cheese', 'olives'] }); // list
```
It runs the same checks and scripts as typing does, and resolves with `{ field, status }`: `status`
is `'applied'`, `'unchanged'`, or `'rejected'` when the form's own validation refused the value.
The field shows the new value at once, before the engine answers, and the promise resolves once it
has. What the form's scripts calculate from it goes with it, as one change: one request, and one
step to undo. The field stays editable meanwhile; filling it in again is the next change. A value
the engine refuses goes back to the one the field had.
Your own inputs can fill in fields too. `form.controlOf(ref)` gives you a field as an Angular
`FormControl`: it holds the field's value, and fills in the field when the control changes, with
the same checks and scripts:
To fill many fields at once, such as from your backend, pass them by name:
```ts
await form.importValues({ 'billing.name': 'Ada Lovelace', 'billing.country': 'NL', agree: true });
```
`importValues()` and `setValues()` write every value as one change, with the calculations run once
after them. Each field's own keystroke and validation scripts don't run, as when a script sets a
field's `value` in Acrobat.
## Check required fields
A form marks some fields as required. Check them before you submit or download:
```ts
const { valid, missing } = form.validate();
const widget = !valid && form.getWidget(missing[0].widgets[0]);
if (widget) stage.reveal(widget.page, { rect: widget.rect });
```
`missing` lists the required fields that are empty, in page order, so you can take the user to the
first one. Only the fields the user may fill in count: another signer's are theirs to fill.
## Calculations, formatting and validation
Many forms add up totals, format dates and check values with scripts. With JavaScript on in the
[actions plugin](documents/actions), they run as people type, as in Acrobat:
When a script refuses a value, such as a date in the wrong format, the field keeps its old value,
the box keeps what was typed so it can be corrected, as in Acrobat, and
`onValidationRejected``validationRejected$` tells you why, so you can show a message.
The scripts read the form as the user sees it, values still on their way included, so nothing is
read from the engine for them. Their engine starts when the first field of a form with scripts takes
focus, so the first value doesn't wait for it; a form without scripts never starts it.
## Reset the form
```ts
await form.reset(); // every field the user may fill in, back to its default
await form.reset([name.ref, email.ref]); // some fields
```
## Move form data in and out
For your own backend, plain values are simplest:
```ts
const values = form.exportValues(); // { 'billing.name': 'Ada Lovelace', agree: true, … }
await form.importValues(values);
```
Fields are matched by their full name. A field the form doesn't have, or a value it can't take, is
skipped; the rest still land.
To copy the fields themselves to another document, with their boxes, values and scripts, take
them out as a bundle and import it there. `FormTransfer` turns a bundle into one JSON text to
store, and back:
```ts
const bundle = await form.export(); // every field; or form.export({ fields }), ({ pages })
const text = FormTransfer.stringify(bundle);
const { fields, dropped } = await otherForm.import(await FormTransfer.parse(text));
```
The import adds the fields as one change you can undo. A field whose name the form has already is
left out and listed in `dropped`. By default each field keeps who created and filled it in, which
needs `canRestoreAttribution()`; pass `{ attribution: 'stamp' }` to make them yours. See
[Import & export](/docs/engine/forms/import-export).
## Methods
What `useForm()` gives you for reading and filling. The verbs that change the form itself are
on [Building forms](forms/building#methods).
| Method | What it does |
| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| `get(ref)` | One field, with its value, or `null` when the form has no such field. [Read the form](#read-the-form) |
| `getValue(ref)` | One field's value, in the shape `setValue()` takes, or `null`. In a component, use `useFormValue(ref)`. |
| `getFieldForWidget(widget)` | The field a box belongs to, from the box's ref |
| `getWidget(widget)` | A box's row: its page, its place (`rect`), its look and its state, or `null` when no page shows it |
| `getWidgets(ref)` | Every box a field shows in, as rows in the field's order: a radio group's buttons, or a field repeated on several pages |
| `listWidgets(page)` | Each field box on a page, with its place, its control, its value and whether it can be filled. For drawing the fields yourself. |
| `getWidgetAt(page, point)` | The field box under a point on a page, with its field, or `null` |
| `setValue(ref, value)` | Fills in a field with `{ value }`, `{ checked }` or `{ selectedValues }`, running the form's checks and scripts. Resolves `{ field, status }`. [Fill in a field](#fill-in-a-field) |
| `setValues(entries)` | Fills in several fields, each `{ ref, value }`, as one change with one recalculation; a field you may not fill in, or a value it can't take, fails on its own. Resolves `{ applied, skipped, failed }`. |
| `importValues(values)` | Fills in fields by full name from a plain object, as one change with one recalculation. Resolves `{ applied, skipped, failed }`. [Move form data in and out](#move-form-data-in-and-out) |
| `exportValues()` | Every value, keyed by full name, as a plain object |
| `export(selection?)` | Whole fields with their boxes, values and scripts, as a bundle: every field, or `{ fields }` or `{ pages }`. [Move form data in and out](#move-form-data-in-and-out) |
| `import(bundle, options?)` | Adds a bundle's fields, as one change. Resolves `{ fields, refMap, dropped }`. Needs `canDesign()`. [Move form data in and out](#move-form-data-in-and-out) |
| `reset(refs?)` | Puts back each field's default, for every field the user may fill in or the fields you pass. Resolves `{ fields }`, the fields it changed. [Reset the form](#reset-the-form) |
| `validate()` | Checks the required fields the user may fill in. Returns `{ valid, missing }`, the empty ones in page order. [Check required fields](#check-required-fields) |
| `activateWidget(widget)` | Does what a click on a field box does, such as running a button's action |
| `getSnapshot()` | Everything at once, as the user sees it: what the engine's `list()` returns, with the values still on their way. `fields`, `widgets`, `formKind`, `needsAppearances` and `calculationOrder` |
| `refresh()` | Reads the whole form again, and `onResynced``resynced$` fires. You rarely need it: the plugin follows every change, whoever made it. |
| `canRead()`, `canFill(ref)` | Whether reading the form, and filling in a field, are allowed. [Permissions](#permissions) |
| `getSettings()`, `updateSettings(changes)`, `resetSettings()` | Reads the settings, changes them while the app runs, or goes back to what you registered. In a component, use `useFormSettings()`. [Settings](#settings) |
Every method that returns a promise also takes a `signal` in its options, to cancel it.
## State
| Field | What it is | Read once |
| :-------------- | :---------------------------------------------------------------------------------------------- | :--------------------------------------------------- |
| `fields` | Every field, with its value | `list()`, or `list({ family, page, name })` for some |
| `status` | Whether the form is read: `'idle'`, `'loading'`, `'ready'`, `'forbidden'` or `'error'` | `getStatus()` |
| `formKind` | What the document has: `'none'`, `'acroform'` (a regular PDF form) or `'xfa'` | `getFormKind()` |
| `selectedField` | In design mode, the field of the selected box, or `null`; see [Building forms](forms/building#change-a-fields-settings) | `getSelectedField()` |
For one field, `useFormValue(ref)` only when that field's value changes.
## Settings
Set them when you register the plugin, and change them while the app runs with
`form.updateSettings({ … })`; `form.resetSettings()` goes back to what you registered, and
`useFormSettings()` gives you the current settings.
| Setting | What it does | Default | From CSS |
| :------------------ | :------------------------------------------------------------------------- | :--------------------------- | :----------------------------- |
| `validation` | Run the form's own checks (`'scripts'`), or accept every value (`'none'`) | `'scripts'` | — |
| `focus.color` | The ring around the field being filled in | the viewer's accent | `--epdf-form-focus` |
| `fields.border` | The edge of a field that has no border of its own | the viewer's accent at 55% | `--epdf-form-field-border` |
| `fields.background` | Inside a field that has no background of its own | `'rgb(255 255 255 / 0.92)'` | `--epdf-form-field-background` |
| `fields.color` | The check mark and text of a field that has no color of its own | `'#1f2a44'` | `--epdf-form-field-color` |
| `fillable` | Which fields people fill in by hand: `true`, `false`, or field families | `true` | — |
Scripts need JavaScript on in the actions plugin; without it, `'scripts'` accepts every value too,
and a form with scripts logs a hint once.
`fillable` is for the people using your app. A field it leaves out draws as a read-only field
does, and takes no typing, clicks or picks; your code still fills it in with `setValue()` and
`importValues()`, and `canFill(ref)` doesn't change:
```ts
formPlugin({ fillable: false }); // show the values, take no input
form.updateSettings({ fillable: ['text', 'checkbox'] }); // only these families
form.updateSettings({ fillable: true }); // every field again
```
The families are `'text'`, `'checkbox'`, `'radio'`, `'combobox'`, `'listbox'`, `'pushbutton'` and
`'signature'` (signing a field is filling it in). To stop your code too, leave `doc.forms.fill` out
of the scope (see [Permissions](#permissions)).
The colors are what the viewer draws around fields; a field's own colors are saved in the PDF (see
[Building forms](forms/building)). A CSS variable wins over the setting: see
[Colors & theming](ui/theming).
## Events
| Event | Fires when | Carries |
| :--------------------- | :------------------------------------------------------------------------ | :---------------- |
| `onValueChanged` | A field's value changed | `field`, `origin` |
| `onValidationRejected` | The form's validation refused a value | `field`, `issues` |
| `onResynced` | The whole form was read, as when it opens, after `refresh()` or a repair | `snapshot` |
| `onSettingsChanged` | The settings changed | `settings`, `changed` |
Fields that are added, changed or removed have their own events; see
[Building forms](forms/building#events).
## Permissions
| Permission | What it allows | Check |
| :--------------- | :--------------- | :------------------ |
| `doc.forms.read` | Reading the form | `form.canRead()` |
| `doc.forms.fill` | Filling it in | `form.canFill(ref)` |
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](/docs/engine/forms/groups).
## Good to know
### Forms and annotations
A field's widgets are the form's: the annotation plugin never lists them. With the
[annotation plugin](annotations) registered, the `` and the annotation layer share the page: fields stay fillable with the
`pointer` tool, and become movable boxes in [design mode](forms/building).
### Keyboard
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
On the local engine, the values live in the document in this tab until it's downloaded.
With CloudPDF, each value is stored on your server as it's entered, so a half-filled form survives a
closed tab, and your backend reads the answers without asking the user to download or upload a
file.
Each value is stored on your server as it's entered, so a half-filled form survives a closed tab.
### XFA forms
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](/docs/engine/forms#xfa-forms).
### Signed documents
A signature can lock the whole form, or some fields. Locked fields show their values and can't be
changed; see [Signatures](forms/signatures).
---
### Cloudpdf Website Src Content Docs Server Configuration Index (`cloudpdf/website/src/content/docs/server/configuration/index.mdx`)
---
title: Configuration reference
description: Every CLOUDPDF_* environment variable the CloudPDF server reads, with defaults and where each one matters.
---
import { Callout } from '@/components/docs/callout';
import { Cards, Card } from '@/components/docs/cards';
# Configuration reference
The server is configured entirely through environment variables. The same
variables work whether you run it via [npm](/docs/server/deployment/npm),
[Docker](/docs/server/deployment/docker),
[Compose](/docs/server/deployment/docker-compose), or
[Helm](/docs/server/deployment/helm) — only *how* you set them differs.
Only one variable is strictly required:
CLOUDPDF_LICENSE_KEY (see
Licensing). With a
development key, everything else has a sensible default — a minimal server
runs with just that. Any other license kind also requires
CLOUDPDF_JWT_SECRET and
CLOUDPDF_PASSWORD_VERIFICATION_HMAC_SECRET (plus
CLOUDPDF_PASSWORD_SESSION_SERVER_SECRET when a KMS is
configured) to be real random values of at least 32 bytes — the server fails
closed at boot and names the variable it needs.
## Licensing
| Variable | Default | Description |
| --- | --- | --- |
| `CLOUDPDF_LICENSE_KEY` | — | **Required.** Your license key; `secret://` references resolve through the secrets providers. |
| `CLOUDPDF_LICENSE_MODE` | `connected` when a key is set | `connected` or `air-gapped`. |
See [Licensing](/docs/server/configuration/licensing).
## Process
| Variable | Default | Description |
| --- | --- | --- |
| `PORT` | `3000` | Port the HTTP server listens on. |
| `HOST` | `0.0.0.0` | Interface to bind. |
| `CLOUDPDF_WORKER_POOL_SIZE` | `min(2, cpus)` | Native PDFium worker threads. Integer, or `max` to use all cores. See [Health & scaling](/docs/server/operations/health-and-scaling). |
## Engine plane
| Variable | Default | Description |
| --- | --- | --- |
| `CLOUDPDF_ENGINE_ISOLATION` | `inline` | `host` runs PDFium in a supervised child process: a native crash costs a sub-second engine respawn instead of the instance. See [Health & scaling](/docs/server/operations/health-and-scaling). |
| `CLOUDPDF_ENGINE_SHARDS` | `1` | Host mode: split the engine into K child processes (worker total must divide evenly). One crash costs 1/K of open documents. |
| `CLOUDPDF_ENGINE_MAX_IN_FLIGHT` | workers × 2 | Admission cap on concurrently dispatched engine jobs; beyond the bounded queue the server sheds with `503` + `Retry-After`. |
| `CLOUDPDF_ENGINE_BG_MAX_IN_FLIGHT` | ⌊workers / 2⌋ | Of the cap, how much background work (thumbnail warming) may occupy. `0` disables the background lane entirely. |
| `CLOUDPDF_ENGINE_RECYCLE` | off | `1` opts into memory-watermark engine recycling (host mode). Companion knobs: `_RECYCLE_SOFT_PCT` (70), `_RECYCLE_HARD_PCT` (85), `CLOUDPDF_ENGINE_MAX_RSS_MB`, `CLOUDPDF_ENGINE_MAX_LIFETIME_HOURS`. |
| `CLOUDPDF_ENCODE_IN_ENGINE` | on | `0` reverts image encoding to the API process (one-release escape hatch; rasters cross the engine boundary raw). |
## Authentication
| Variable | Default | Description |
| --- | --- | --- |
| `CLOUDPDF_JWT_SECRET` | dev fallback | HS256 secret used to verify document and admin tokens. Must match the secret your backend signs with. **Required (≥32 bytes) under a production license**; development keys fall back to a public dev value with a warning. |
| `CLOUDPDF_API_AUTH_TOKENS` | — | Comma-separated static API tokens for trusted backends and tooling (root credential for the admin plane). ≥32 bytes each under a production license. |
| `CLOUDPDF_PASSWORD_VERIFICATION_HMAC_SECRET` | dev fallback | HMAC pepper for the encrypted-PDF password-verification cache — it keeps stored password proofs non-reversible. **Required (≥32 bytes) under a production license**, whether or not you open encrypted PDFs. |
| `CLOUDPDF_PASSWORD_SESSION_SERVER_SECRET` | dev fallback | Server key material for encrypted-PDF unlock sessions. **Required (≥32 bytes) under a production license when a KMS is configured**; unused otherwise. |
| `CLOUDPDF_PASSWORD_SESSION_SERVER_SECRET_ID` | `dev-v1` | Label for the active session secret, recorded on each session. Changing it (or the secret) invalidates existing sessions. |
See [Authentication](/docs/server/configuration/authentication), and
[Encrypted-PDF secrets](/docs/server/configuration/authentication#encrypted-pdf-secrets)
for what the last three protect.
## Database
| Variable | Default | Description |
| --- | --- | --- |
| `CLOUDPDF_DB_DRIVER` | `sqlite` | `sqlite` or `postgres`. |
| `CLOUDPDF_DB_SQLITE_PATH` | `./data/cloudpdf.db` | SQLite file path (when driver is `sqlite`). |
| `CLOUDPDF_DB_URL` | — | Postgres connection string (required when driver is `postgres`). |
See [Database](/docs/server/configuration/database).
## Storage (object store)
| Variable | Default | Description |
| --- | --- | --- |
| `CLOUDPDF_STORAGE_KIND` | `fs` | `fs`, `s3`, `gcs`, or `azure-blob`. |
| `CLOUDPDF_STORAGE_FS_ROOT` | `./data/objects` | Directory for stored objects (when kind is `fs`). |
| `CLOUDPDF_STORAGE_S3_BUCKET` | — | Bucket name (S3). |
| `CLOUDPDF_STORAGE_S3_REGION` | — | Bucket region (S3). |
| `CLOUDPDF_STORAGE_S3_ENDPOINT` | — | Custom endpoint for S3-compatible stores (e.g. MinIO). |
See [Storage](/docs/server/configuration/storage).
## Imports (server-side pull)
On by default with a safe posture (HTTPS-only, public networks, 128 MiB cap).
Registered connections let the server pull from your own buckets without
presigning.
| Variable | Default | Description |
| --- | --- | --- |
| `CLOUDPDF_IMPORT_ENABLED` | on | Set `0` to disable the import endpoint. |
| `CLOUDPDF_IMPORT_MAX_BYTES` | `128 MiB` | Per-document transfer ceiling. |
| `CLOUDPDF_IMPORT_TIMEOUT_MS` | `120000` | Wall-clock budget per transfer attempt. |
| `CLOUDPDF_IMPORT_MAX_CONCURRENT` | `4` | Concurrent transfers per replica (sync + async). |
| `CLOUDPDF_IMPORT_ALLOW_HTTP` | off | Permit `http://` URL sources (dev / MinIO). |
| `CLOUDPDF_IMPORT_ALLOW_PRIVATE_NETWORKS` | off | Permit private-address URL sources (dev / in-VPC). |
| `CLOUDPDF_IMPORT_CONNECTIONS` | — | Comma-separated registry of named pull sources (S3, GCS, Azure Blob, filesystem), each configured via `CLOUDPDF_IMPORT_CONNECTION_*` variables. |
See [Imports](/docs/server/configuration/imports).
## Engine cache
The cache holds recently used documents and renders so repeat requests are fast.
It is disposable — the server rebuilds it from the object store.
| Variable | Default | Description |
| --- | --- | --- |
| `CLOUDPDF_CACHE_ROOT` | `./data/cache` | Cache directory. |
| `CLOUDPDF_CACHE_MAX_BYTES` | `4 GiB` | Maximum cache size before eviction. |
## Fonts
| Variable | Default | Description |
| --- | --- | --- |
| `CLOUDPDF_FALLBACK_FONTS` | — | JSON array of fallback fonts (`{ key, path, … }`) for glyphs a document's own fonts are missing. |
See [Fallback fonts](/docs/server/configuration/fonts).
## Lifecycle & migrations
| Variable | Default | Description |
| --- | --- | --- |
| `CLOUDPDF_AUTO_MIGRATE` | on for SQLite, off for Postgres | Apply pending migrations on boot. |
| `CLOUDPDF_FAIL_ON_PENDING` | off | Refuse to start if migrations are pending. Recommended for multi-replica deploys. |
| `CLOUDPDF_AUTO_PROVISION_TENANT` | off | Lazily create tenant rows. Dev convenience — leave off in production. |
See [Migrations](/docs/server/operations/migrations).
## Shutdown & observability
| Variable | Default | Description |
| --- | --- | --- |
| `CLOUDPDF_SHUTDOWN_TIMEOUT_MS` | `30000` | Budget for closing in-flight HTTP during shutdown before teardown proceeds anyway. Keep it below your orchestrator's kill deadline. |
| `CLOUDPDF_SHUTDOWN_DRAIN_MS` | `0` | Settle window after `/readyz` flips to 503 (and SSE streams end) before the listener closes — for probe-driven load balancers. |
| `CLOUDPDF_METRICS` | off | `1` exposes an unauthenticated Prometheus `/metrics` endpoint (scrape it inside your private network). |
## Optional adapters
These are opt-in. You only need them for the corresponding feature.
| Variable | Default | Description |
| --- | --- | --- |
| `CLOUDPDF_CDN_KIND` | `none` | Sign delivery URLs via a CDN: `bunny`, `cloud-cdn`, `cloudfront`, `azure-fd`, `custom-hmac`. |
| `CLOUDPDF_KMS_KIND` | `static` | Key management for encrypted-PDF sessions: `aws-kms`, `gcp-kms`, `azure-kv`. |
| `CLOUDPDF_SECRETS_PROVIDERS` | `env` | Comma-separated registry of secret sources. |
See [CDN, KMS & secrets](/docs/server/configuration/adapters).
The CLI prints this whole surface at any time:
cloudpdf-server --help.
## Where to set these
---
### Cloudpdf Website Src Content Docs Server Deployment Index (`cloudpdf/website/src/content/docs/server/deployment/index.mdx`)
---
title: Deployment overview
description: Choose how to run the CloudPDF server — npm, Docker, Docker Compose, or Helm — based on your scale and operational needs.
---
import { Cards, Card } from '@/components/docs/cards';
import { Callout } from '@/components/docs/callout';
# Choosing a deployment
The server is one application, packaged four ways. They run the same binary and
read the same [`CLOUDPDF_*` configuration](/docs/server/configuration), so the
choice is purely about *how you want to operate it* — not what it can do.
| Method | Best for | Typical database | Typical storage | Scaling |
| --- | --- | --- | --- | --- |
| [**Node / npm**](/docs/server/deployment/npm) | Local dev, existing Node platforms, custom hosts | SQLite or Postgres | Disk or cloud | Manual |
| [**Docker**](/docs/server/deployment/docker) | Single host, simple self-hosting, CI | SQLite or Postgres | Disk or cloud | Manual / your orchestrator |
| [**Docker Compose**](/docs/server/deployment/docker-compose) | A full self-hosted stack on one box | Postgres (included) | MinIO / S3 (included) | A few replicas, one host |
| [**Helm / Kubernetes**](/docs/server/deployment/helm) | Production, startup → enterprise | Postgres (managed) | S3 / GCS / Azure (managed) | Autoscaling, multi-replica, HA |
You can always start small and grow. Because storage is configured, not
compiled in, moving from SQLite + disk to Postgres + S3 — or from Docker to
Kubernetes — is a configuration change, not a rewrite.
## A quick decision guide
- **Just exploring, or developing locally?** Use [npm](/docs/server/deployment/npm)
or the [Quick start](/docs/server/getting-started/quick-start) Docker one-liner.
- **Self-hosting on a single server or VM?** Use
[Docker](/docs/server/deployment/docker) for the server alone, or
[Docker Compose](/docs/server/deployment/docker-compose) for the server plus
Postgres and object storage in one file.
- **Running in production, or need high availability?** Use
[Helm](/docs/server/deployment/helm). You get multiple replicas, autoscaling,
managed schema migrations, and a clean separation of secrets — the things that
matter when downtime is expensive.
## What every method needs
No matter how you deploy, the server needs:
1. **A signing secret** — `CLOUDPDF_JWT_SECRET`, shared with the backend that
mints tokens. See [Authentication](/docs/server/configuration/authentication).
2. **A database** — SQLite (default) or Postgres. See
[Database](/docs/server/configuration/database).
3. **An object store** — local disk (default) or a cloud bucket. See
[Storage](/docs/server/configuration/storage).
4. **Persistent volumes** for `/data` when you use SQLite, local storage, or the
local cache.
For anything customer-facing: set
CLOUDPDF_ENGINE_ISOLATION=host so a native PDF crash costs a
sub-second engine respawn instead of the instance, and run more
than one replica (Compose or Helm) so a single failure can't take
you offline. Details in
Health & scaling.
## Pick your path
---
### Cloudpdf Website Src Content Docs Server Getting Started Index (`cloudpdf/website/src/content/docs/server/getting-started/index.mdx`)
---
title: Introduction
description: The CloudPDF server — a self-hostable PDF engine that renders pages, extracts text, manages annotations, and serves documents over a secure HTTP API.
---
import { Cards, Card } from '@/components/docs/cards';
import { Callout } from '@/components/docs/callout';
# The server
`@cloudpdf/server` is the backend that powers CloudPDF. It runs native PDFium on
your own infrastructure and exposes it as a clean, document-scoped HTTP API:
open a document, render pages, extract text, read and write annotations, inspect
metadata, and enforce access — all behind short-lived JWTs.
It is the same engine that runs locally in the browser with EmbedPDF, lifted
onto the server. Your frontend keeps talking to one [`Engine`
interface](/docs/engine); the server does the heavy PDF work, holds your
documents, and never hands storage credentials to the client.
In a hurry? The Quick start
gets a server answering requests in about a minute with a single
docker run.
## Why run your own server
- **Your data stays yours.** Documents live in your database and object store —
SQLite and the local disk to start, Postgres and S3/GCS/Azure when you grow.
- **Real PDF rendering.** Native PDFium renders pages to PNG/WebP and extracts
text and geometry — the same fidelity as the desktop, on the server.
- **Secure by construction.** Every document route requires a short-lived,
document-scoped JWT minted by your backend. The browser never sees your
tenant secret or storage keys.
- **Runs anywhere.** A single Node process, a Docker container, or a
Kubernetes deployment that scales from a side project to enterprise traffic.
## Three ways to run it
The server is a single, self-contained application. Pick the packaging that fits
your team — they all run the exact same binary and read the exact same
[configuration](/docs/server/configuration).
Don't want to host anything? CloudPDF Cloud runs this same
server for you as a managed SaaS. The API is identical, so you can start on the
cloud and move to self-hosted later — or the other way around — without
changing a line of frontend code. [See plans and start a free trial](/pricing).
## Next steps
---
### Cloudpdf Website Src Content Docs Viewer Features Index (`cloudpdf/website/src/content/docs/viewer/features/index.mdx`)
---
title: All features
description: Everything the viewer can do, how to leave a feature out, who the user is, and where each feature's settings go.
---
{/* 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:
```js
{ disable: ['forms', 'redaction', 'measurement'] }
```
| Feature | What people can do | Settings |
| :-- | :-- | :-- |
| `annotations` | Highlight, underline and strike out text; draw; add notes, text boxes and callouts | [Annotations](features/annotations) |
| `shapes` | Draw rectangles, circles, lines, arrows and polygons | [Annotations](features/annotations#the-tools) |
| `comments` | Comment on annotations and reply, in a panel with every thread | [Annotations](features/annotations#comments) |
| `stamps` | Place stamps: the standard ones, their own, or images | [Annotations](features/annotations#stamps) |
| `signatures` | Draw, type or upload a signature; sign fields; check signatures | [Forms & signatures](features/forms-and-signatures#signatures) |
| `forms` | Fill in forms; build them in the Form mode | [Forms & signatures](features/forms-and-signatures) |
| `redaction` | Mark text and areas, then remove them from the file for good | [Annotations](features/annotations#redaction) |
| `measurement` | Measure distances, perimeters and areas at the drawing's scale | [Annotations](features/annotations#measurements) |
| `pages` | Rotate, move, insert, duplicate and delete pages in the thumbnails panel, each step undoable | [Panels](customize/panels#organize-pages) |
| `attachments` | See, save, attach and remove files inside the PDF | [Panels](customize/panels#the-attachments) |
| `search` | Find text, with every match highlighted and listed | [`plugins.search`](/docs/headless/text/search#settings) |
| `text` | Select and copy text | [`plugins.selection`](/docs/headless/text/selection#settings) |
| `thumbnails` | A picture of every page, to jump around | [Panels](customize/panels) |
| `outline` | The document's table of contents | [Panels](customize/panels) |
| `documents` | Open other files (with the local engine), download, print, several documents in tabs | [Documents](documents) |
## Leave features out
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](features/turning-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
The user's name becomes the author of the annotations and comments they make:
```js
{ identity: { displayName: 'Ada Lovelace' } }
```
The user's name becomes the author of the annotations and comments they make. On CloudPDF, who the
user is and what they may do come from the document's token, so your server decides.
## Each feature's settings
Every feature is a headless plugin, and `plugins` takes its settings by the plugin's name, exactly
as the plugin's page lists them:
```js
{
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](code/plugins) for every plugin and how to change its settings
while the viewer runs.
## Good to know
### What loads when
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](concepts/how-it-works#what-loads-when)
has the whole order.
---
### Conventions Architecture (`docs/conventions/architecture.md`)
# Architecture
How the client stack is put together: what a plugin is, where its state lives,
how engine data reaches the UI, and how a plugin's files are laid out. The
details live in [`state-and-sync.md`](./state-and-sync.md),
[`events.md`](./events.md) and [`plugins.md`](./plugins.md).
## A plugin in one paragraph
A plugin provides one capability per scope: one for the workspace, or one for
each open document. The kernel builds it by calling the plugin's
`create(ctx)`. The capability is the plugin's only public surface: synchronous
reads, verbs that do work, and events. Inside, a plugin holds up to four kinds
of state, each with one home and one way to change. It talks to the engine
only through `ctx.doc`, and to other plugins only through their capabilities.
## Layers
| Layer | Packages | Responsibility |
| ---------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Engine | `@embedpdf/engine-core` (the contract), `@embedpdf/engine` (local), `@cloudpdf/engine` (cloud) | Reads and writes PDF documents; publishes one confirmed event per mutation. |
| Kernel | `@embedpdf/core` | Scopes, plugin lifetime, the store, capability resolution, mirrors. |
| Pure cores | `@embedpdf/core-*` | One domain's logic, testable without a kernel, engine or DOM. |
| Plugins | `@embedpdf/plugin-*` | One capability each, built on the kernel. |
| Adapters | `@embedpdf/react`, `@embedpdf/angular`, `@embedpdf/web` | Render capabilities in one framework; read only through capabilities. |
| Viewer | `@embedpdf/viewer`, `@embedpdf/viewer-*` | The finished viewer, built on the adapters. |
Where each package lives and what it is called: [`packages.md`](./packages.md).
An adapter paints from what a plugin hands out, and decides no geometry. When a
picture needs a placement, the plugin's read carries it resolved: an
annotation render item comes with its `frame` and `raster`, and the adapter
only converts page units to pixels with `@embedpdf/web` (`frameInPixels`,
`rasterInPixels`). The one core function adapters call is the annotation
core's `scene()`, the drawing vocabulary every painter maps onto its own
elements.
## Scopes and bring-up
A plugin declares `scope: 'workspace'` (the default: one instance for the
kernel) or `scope: 'document'` (one instance per open document).
- **Workspace plugins** are created by `createKernel`, in dependency order.
Their `connect` runs in `kernel.start()`.
- **Document plugins** are created when a document opens. After the engine has
opened the document and listed its pages, the kernel gives every document
plugin a fresh state cell, then, in dependency order, runs each plugin's
`create`, then its `connect`, then starts the first load of the mirrors that
plugin created.
A document open is transactional. Everything above runs before the document is
published; if a `create` or `connect` throws, every teardown registered so far
runs, the document never becomes ready, and its tab shows `error`. Only after
bring-up does the document appear in `documents.list()` as `ready` and
`documents.onOpened` fire.
Closing a document removes its tab at once, revokes the write access of every
instance's state and mirror cells, aborts the instance lifetime (pending
`ctx.doc` calls reject with `instance-closed`), runs every registered teardown
in reverse order, and then fires `documents.onClosed`.
## Four kinds of state
| Kind | What it is | Where it lives | How it changes | Examples |
| -------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Mirror | A local copy of data the engine owns | `ctx.mirror(spec)` or `ctx.pageMirror(spec)`: a store cell of its own | Only by folding confirmed engine events (every origin) and by loads. Verbs never write it. | form fields, annotation records, metadata, signatures, links per page, text geometry per page |
| Pending change | A change this session staged that the engine hasn't answered | The document's change queue (`ctx.changes`), shared by its plugins; mirrors show it in `view()` | Staged by a verb or gesture; leaves the views once the engine answered and each mirror holds the answer, or at once when refused | three annotations the user moved, shown at their new places until the engine answers |
| Session | State the client owns that is not in the PDF | `ctx.state` | Only through named pure transitions in `model.ts` | camera, open surfaces, active tool, selection, search session, in-flight flags |
| Resource | Anything that is not plain data: handles, rasters, workers, registries of functions, caches | Closures in the controller, released through `ctx.cleanup` or `ctx.acquire` | However the owner likes; readers are woken with `ctx.notify()` | raster store, tile manager, command and tool registries, script sandboxes |
What the UI sees is each mirror's `view()` (the confirmed value with the
pending changes replayed on top) and session state, combined by pure,
memoized reads.
Rules:
- A mirror always holds what the engine confirmed. Nothing optimistic enters
it.
- A pending change leaves the views when the engine answered: an applied one
once each mirror holds the answer, a refused one at once. Rollback is
leaving: the views show the mirror again, never a copy taken before the
change.
- A new object is named at birth: its create takes a reserved object number
(`ctx.changes.takeObjectNumber()`), so everything that holds it before the
engine answers holds its final ref.
- State is plain data: no functions, class instances, handles, `Map`s or
`Set`s in `ctx.state` or a mirror. Anything else is a resource.
- No state exists only to wake the UI. A counter bumped so that selectors
re-run is a `ctx.notify()` call instead.
[`state-and-sync.md`](./state-and-sync.md) describes each kind's API.
## Data flow
```
user gesture or API call
│
▼
capability verb ──► ctx.changes.stage(change) ──► every mirror's view() shows it
│
▼
doc.apply(change), after everything staged before it
│ another session's mutation
▼ │
engine confirms ─► document event (origin: local) ◄───┘ (origin: remote)
│
▼
mirror fold(value, event) ── the same code for every origin
│
├─► new mirror value (its store cell)
├─► the answered change leaves the view
└─► the plugin's fact events fire (origin = event.origin)
│
▼
store change ─► adapters re-run selectors ─► pure memoized reads ─► UI
```
Both engines publish the event for a session's own mutation before the
mutation's promise settles (see `DocumentEvent` in
`packages/engine/core/src/events/DocumentEvent.ts`, checked by
`runDocumentEventsConformance`). So when a verb's `await` returns, the fold has
already run: a verb never needs `waitFor`, a revision check or a refetch to see
its own write.
## Events
A capability exposes three kinds of events:
| Kind | Meaning | Fired from | Origin |
| ------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| Fact | Something changed in the document | Where the confirmed document event is applied: a mirror's `changed` callback, or the plugin's one listener for that event | `event.origin` |
| State change | A session value changed | The plugin's `ctx.state.onChange` listener, comparing previous and next | none |
| Occurrence | An operation ran, finished or failed | Where the operation reaches that point | a domain field when one is needed |
An event fires from exactly one place. Events report what happened; what
something is, is read through a getter. Details: [`events.md`](./events.md).
## Reads
- Reads are synchronous and pure: `get*`, `list*`, `is*`, `has*`, `can*`.
- A read returns the same object until its inputs change, so adapter
selectors compare with `Object.is`. Build such reads with `memo` and
`memoByKey` from `@embedpdf/core`, not with hand-written caches.
- Reads never start engine work. Loading starts with `ensureLoaded(page)`, or
by the mirror itself.
## Reactions
Some plugins do not copy engine data but must respond to it: render
invalidates rasters, search re-runs its query, signature re-judges its
verdicts, actions clears its trigger cache. A reaction:
- subscribes with `ctx.listen(ctx.doc.events, …)` inside `connect`;
- ignores origin for what it does;
- only invalidates its own caches or re-runs its own operations. It never
writes another plugin's data.
## Pure cores
A `core-*` package exists when a domain needs logic worth testing without a
kernel, engine or DOM: page geometry (`core-geometry`), the camera and scene
(`core-stage`), annotation gestures and hit-testing (`core-annotation`), the
toolbar solver (`core-ui`).
- Inputs in, decision out: plain functions, or `update(model, message)`
returning the next session, the records it changed and the effects, as in
`core-annotation`. No I/O, no clock, no randomness.
- A core never stores engine data. It reads the records it works on from its
input and returns what it changed; the plugin decides where that lives.
- The plugin's controller performs the effects. A core does not call the
engine.
- Cores know nothing about mirrors, overlays or events. They receive the data
they need as arguments.
- A plugin's own pure functions live in its `model.ts`, not in a second
`core/` folder.
## Plugin anatomy
```
packages/plugin//src/
.plugin.ts the manifest: definePlugin({ id, token, scope, requires, optional, state, create })
token.ts createCapabilityToken(...), called once per package
contract.ts the public lens: capability interface, public types, the token re-exported
host-contract.ts optional: the host lens, the same token widened with createHostToken
internal.ts optional: framework-only helpers (a visibility boundary, not a bundle boundary)
index.ts the plugin factory and `export * from './contract'`
model.ts state shape, initial state, pure transitions, pure projections and folds
controller.ts create(ctx): builds the capability and returns { api, connect? }
connect.ts optional: registrations with sibling plugins, called from connect
# larger plugins split the controller into areas:
services/ plugin-private helpers shared by the areas
read/ write/ sync/ tools/ one area per file, composed with composeApi
packages/plugin//test/ mirrors src/
```
Rules:
- The manifest holds no logic. Everything that registers with a sibling
lives in `connect.ts` and runs inside `connect`.
- `create` returns `{ api, connect? }`, and `controller.ts` is where it is
built.
- Every registration's `Unsubscribe` goes to `ctx.cleanup`, even when both
sides close together.
- Tests mirror `src/` under `test/`.
Each file's role, the manifest fields, contracts and lifetime helpers:
[`plugins.md`](./plugins.md).
---
### Conventions Comments (`docs/conventions/comments.md`)
# Comments
A comment explains what the code cannot say: why it is this way, what must
stay true, what a specification requires, or what surprising input looks like.
It is written for a developer who has only this repository in front of them.
## Rules
1. **Self-contained.** A comment never depends on anything outside the
repository. Never cite plans, decision numbers, phases, gates, work
packages, internal section numbers, reviews, chats or tickets. If a rule
matters, state it in the comment, or in a committed document and link that
document by its repository path.
2. **Allowed references:**
- external specifications with a section: `ISO 32000-2 §12.5.6.3`, `RFC 3161`;
- the observable behavior of external products: `matches Acrobat: …`;
- committed documents by path: `docs/conventions/state-and-sync.md`;
- code symbols with `{@link Symbol}`.
3. **Present tense, current behavior.** No history: not "v2 behaviour",
"matches v2", "the old mistake", "used to", "as before", "legacy",
"interim" or "for now". The engine is "the engine", not "the v3 engine".
Migration notes belong in changesets and the migration guide.
4. **No roadmap.** Future work is `TODO(#123): …` pointing at a GitHub issue,
or it is not in the code.
5. **One owner per explanation.** Explain an invariant once, where it is
enforced. Elsewhere, link to that symbol instead of repeating it.
6. **Public API is documented with TSDoc.** Every member of `contract.ts` and
`host-contract.ts` gets:
- a one-sentence summary;
- the `PluginError` codes it rejects with and the events it fires, when it has any;
- `@param`/`@returns` only when the names do not already say it.
7. **Length:**
- inline comments: one to four lines;
- a module header: what the module is responsible for, in at most about ten lines;
- longer design explanations go into `docs/conventions/` or a package README, linked from the code.
8. **Tone.** No ALL-CAPS for emphasis; acronyms are fine. If something must
never happen, write "must not", and back it with a type or a test.
9. **No commented-out code, no names of people, and no dates**, unless the date
is part of a specification or protocol.
10. **Section dividers** (`// ── reads ──`) are allowed in files over roughly
150 lines. Always use this format.
## Examples
| Instead of | Write |
|---|---|
| `// the snapshot can never settle stale (G5).` | `// Queue one more read, so the snapshot never settles on data older than the last invalidation.` |
| `// the nine members the authoring pattern needs (see the road-to-3.0 plan, §5.10)` | `// The guarded document handle, page geometry, mirrors, events and lifetime helpers, all bound to one instance.` |
| `// Faint reference cross, prominent live indicator (v2 feel).` | `// A faint reference cross and a prominent live indicator.` |
| `// feeding it a units conversion (the old mistake) shrank bodies` | `// A px-per-point scale here would shrink screen-anchored bodies at 100% zoom; this is a zoom ratio.` |
| `// Phase 3's shared ScriptHost swaps in by re-registering` | Describe what the code does now, and nothing else. |
| `// The ONE place the value changes` | `// The only place the value changes` |
## Enforcement
`pnpm check:comments` runs in CI. It reads comments with the TypeScript
scanner and rejects:
- plan and phase vocabulary, including numbered requirement labels;
- internal section numbers (`§` without an ISO, PDF or RFC citation);
- links to `.md` files that do not exist;
- version-history references;
- `TODO`s without an issue number;
- ALL-CAPS emphasis.
Justified exceptions go in `scripts/check-comments.allow`, one per line with a reason.
---
### Conventions Docs Architecture (`docs/conventions/docs-architecture.md`)
# Docs architecture — author once, render per integration
The law for how documentation is structured so that five integrations never
mean five copies. Framework parity makes this possible: "one page of prose +
per-framework code" is rendering, not aspiration.
Website source paths below are relative to `website/`; paths beginning with
`/docs` are public documentation URLs.
## The two halves
```
/docs
/viewer → the ready-made viewer (snippet + wrappers)
/headless → the adapter packages (@embedpdf/react|vue|svelte|angular)
/engine → engine choice (local wasm vs cloud), runtime, server
```
- **Viewer docs carry the shared integration switcher** for Vanilla JS, React, Vue,
Svelte, and Angular. The config API and prose remain shared; installation and
code examples resolve from the integration in the URL.
- **Headless docs carry the same integration switcher**, limited to React, Vue,
Svelte, and Angular. There is one source page per feature: stage, render,
selection, annotation, form, search, and so on. Prose is shared; code and API
names render per framework.
Viewer and Headless share one persisted integration preference. Switching
products carries React, Vue, Svelte, or Angular with you. Vanilla JS falls back
to React when entering Headless because no Vanilla headless adapter exists.
The concrete URL remains the source of truth; the preference only resolves
variant-less courtesy routes.
## Author once, render per integration
One MDX file per topic. Integration-specific URLs are generated from it:
```
src/content/docs/headless/annotation.mdx
→ /docs/headless/react/annotation
→ /docs/headless/vue/annotation
→ /docs/headless/svelte/annotation
→ /docs/headless/angular/annotation
```
Viewer pages use the same fan-out model:
```
src/content/docs/viewer/quick-start.mdx
→ /docs/viewer/vanilla/quick-start
→ /docs/viewer/react/quick-start
→ /docs/viewer/vue/quick-start
→ /docs/viewer/svelte/quick-start
→ /docs/viewer/angular/quick-start
```
Why per-integration URLs instead of one URL + client switcher: SEO indexes
integration-specific content, links can pin an integration, analytics see per-
integration readership. The catch-all route strips the integration segment,
renders the shared MDX with the integration in context, and
`generateStaticParams` emits the page × integration matrix. The switcher in the
docs header just navigates to the sibling route (choice persisted, deep links
win over persistence).
Inside a page:
- `` — renders the active integration's sample.
- `…` — rare prose branches. If a page needs many of these,
it's a smell: either the wording should be framework-neutral (see
terminology map) or the page belongs in the per-framework fork set.
- The fork set is explicit and small: installation/scaffolding and SSR
integration (Next/Nuxt/SvelteKit/Angular) are separate per-framework pages.
**Terminology map** (one page, linked from every headless page): hook =
composable = store = inject function; `` = ``; etc.
Prose says "the selection hook" and means all four. Writing style guide:
never narrate JSX composition in shared prose.
## Code samples are real code, compiled in CI
The cure for docs rot: samples never live inline in MDX. They live as real
files, type-checked against the actual packages:
```
website/src/samples/
package.json → depends on @embedpdf/react (etc.), workspace:*
react/annotation/quickstart.tsx
vue/annotation/quickstart.vue
svelte/annotation/quickstart.svelte
angular/annotation/quickstart.ts
```
- `pnpm --filter @embedpdf/website-samples typecheck` runs in CI: an API
change fails the build until the docs move with it. This is the docs
equivalent of the consume gate.
- The MDX pipeline (each site's remark/rehype code-example plugins) reads the
files at compile time and highlights them with shiki. An `` or
`` keeps its code out of the compiled page: each framework's files go
to a JSON file in `.next/cache/docs-code/`, keyed by the sample's name and a
hash of the files, and the page only names the key and the frameworks that
have a version. The page's server component (`RouteExample`) reads the
route's framework's files at render (docs-kit `mdx/code-panels`). Inlined, four
frameworks made page modules megabytes each, and the docs route, which
compiles every page, ran the dev server out of memory.
- A missing sample for a framework renders an honest "not yet ported for
{framework}" callout — driven by file presence, not hand-maintained flags.
## The reference is complete, and checked
Every headless plugin page ends with its reference: `## Methods` (everything
`use()` gives you), `## State` (everything `useState()` gives
you, with the getter that reads each value once), then
`## Settings`, `## Events` and `## Permissions`. The rows are written by hand,
in plain words, each linking to the section that shows it.
- Every public member of a plugin's capability is on exactly one page: a
Methods row, a State row's getter, or an Events row. A plugin spread over
several pages splits by its nouns (`annotation.selection.*` on Selecting).
- `docs/content/reference.mjs` says which pages document which capability.
`docs/content/scripts/reference.mjs` reads each capability interface from its
TypeScript source and fails on a member no page lists, a member on two pages,
or a listed name the capability doesn't have. It runs in `docs:check`.
- The pages describe the API the code is moving to. Where they're ahead, the
name is `pending` in the manifest, with why; the check fails once a pending
entry is no longer needed, so the list only shrinks.
- The same check compares the tables with the declarations next to each
contract, once a plugin has them: a State table's `Field` column with its
`defineState()` fields, a Settings table's `Setting` column with its settings
defaults (a row may name a group), and every `From CSS` column with
`EPDF_VARIABLES` in `@embedpdf/web`, both ways.
## A page goes live when its code does
The pages describe the API the code is moving to, so a page isn't shown as
released until its code exists. Two machine checks decide it, per page and per
framework, and run in `docs:check`:
- `docs/content/scripts/snippets.mjs` compiles each framework's snippets against
the packages in the same commit (React with `tsc`, Angular with `ngc` and
`strictTemplates`, Vue with `vue-tsc`, Svelte with `svelte-check`) and writes
`generated/snippet-status.json`. It never fails the build.
- `docs/content/scripts/publish-gate.mjs` writes `generated/live-pages.json`: a
page is live for a framework when its snippets compile for it and none of the
names its Methods, State or Events tables list is `pending`.
The viewer's pages go through the same gate, for five integrations: the four frameworks and
`vanilla`, a plain HTML page. Their snippets compile against `@embedpdf/viewer` at its source.
A `.vanilla.html` snippet's module scripts are taken out of the page and type-checked as
JavaScript, at the page's own line numbers. The reader's own DOM code (`event.target.value`) is
left alone, and the CDN script resolves to the viewer. The page's elements are checked too:
every `` and `` element must be declared in the viewer's types, every
`` attribute must be a config key, a `slot` must name one of the viewer's, on a
child of the viewer, and a `
