--- title: Annotations in code description: Read, create, change, reorder and delete annotations from your own code, with changes shown at once. --- import { Callout } from '@/components/docs/callout'; # Annotations in code Everything people do with the pointer, your code can do too. `useAnnotation()` gives you the annotations on screen, and every change you make shows at once, before the engine has saved it: ```ts const { annotation: square } = await annotation.create(page.ref, { subtype: 'square', box: { x: 72, y: 92, width: 200, height: 100 }, color: '#0078ff', }); await annotation.update(square.ref, { contents: 'Check this table' }); await annotation.delete(square.ref); ``` > **Try it:** each button is one call. **Saving…** shows while the engine writes a change. An annotation here is the engine's record: the same kinds, fields and names as the [engine's annotation pages](/docs/engine/annotations). Each kind's page there lists its fields. These pages cover what the plugin adds on top. ## Read annotations ```ts annotation.list(); // every annotation, in drawing order annotation.list({ pages: [page.ref] }); // one page annotation.list({ subtype: 'highlight' }); // one kind annotation.get(ref); // one, or null annotation.getAt(page.ref, { x: 120, y: 80 }); // the topmost one at a point, or null ``` To keep a component up to date, use `useAnnotationList()`. Your component when the list changes: > **Try it:** pick a kind, then click a row to go to it. Each annotation has a `subtype` (its kind), a `rect` (where it is on its page), a `page` and a `ref`. Keep the `ref`: it's how you change or delete the annotation later. Positions are in points from the top-left of the page; see [Coordinates](../concepts/coordinates). Annotations are loaded in the background when a document opens. `useAnnotationState()` has a `status`: `'loading'` until they're all in, then `'ready'`. ## Create an annotation `create()` takes the page, then the annotation's kind and fields: ```ts const { annotation: note } = await annotation.create(page.ref, { subtype: 'text', rect: { x: 500, y: 72, width: 20, height: 20 }, contents: 'Is this total right?', }); ``` Fields you leave out get the kind's default. For example, a new annotation prints with the page unless you pass `print: false`. Every kind the engine can create, the plugin can too; the [engine's pages](/docs/engine/annotations) show each one. Some options change how the plugin treats the new annotation: ```ts await annotation.create(page.ref, { subtype: 'square', box }, undefined, { tool: 'square', select: true, }); ``` | Option | What it does | | :------- | :--------------------------------------------------------------------------------------------- | | `tool` | Starts from that tool's defaults, the user's current drawing style, before your own fields. | | `select` | Selects the new annotation, as drawing it would. Without it, code never changes the selection. | Stamps and file attachments carry bytes. They go in the third argument, `resources`, named for what they are: a stamp's `appearance`, an attachment's `file`. ```ts const image = await (await fetch('/approved.png')).blob(); await annotation.create(page.ref, { subtype: 'stamp', box }, { appearance: image }); // A file pinned to the page, drawn as an icon, 20 × 20 like a note await annotation.create( page.ref, { subtype: 'file-attachment', rect: { x: 40, y: 60, width: 20, height: 20 } }, { file: pickedFile }, // a File brings its name and type ); ``` For stamps from a library, see [Stamps](stamps). ### From the selected text `createFromSelection()` turns the text a person selected into a highlight, an underline, a strikeout or a squiggly line, one per page: ```ts const { annotations } = await annotation.createFromSelection('highlight'); ``` It takes a tool id, so your own markup tools work too. The text selection is cleared afterwards; pass `{ clear: false }` to keep it. > **Try it:** the title's first line is selected: press **Highlight**. Then select other words > with the pointer and mark them. ## Change an annotation `update()` takes the `ref` and only the fields you want to change: ```ts await annotation.update(ref, { color: '#dc143c', contents: 'Reviewed' }); ``` A field you leave out keeps its value, and `null` removes it (`{ interiorColor: null }` for no fill). You can also pass an annotation you read straight back, which makes "change a copy, then save it" simple: ```ts const square = annotation.get(ref); if (square?.subtype === 'square') await annotation.update(ref, { ...square, opacity: 0.5 }); ``` To move or resize any annotation, send a new `rect`: ```ts const { rect } = annotation.get(ref)!; await annotation.update(ref, { rect: { ...rect, x: rect.x + 40 } }); // 40 points right ``` For a shape drawn from points, like a line or ink, the engine moves every point for you. The rules for resizing are on the engine's [Annotations](/docs/engine/annotations#move-or-resize-by-rect) page. Rotation is a field too: `update(ref, { rotation: 90 })` turns a shape or a stamp to 90° clockwise. A highlight can become an underline, a squiggly line or a strikeout, and a rectangle an ellipse: send the new `subtype`. It stays the same annotation, with its replies and its place in the drawing order: ```ts await annotation.update(ref, { subtype: 'squiggly' }); ``` Which kinds can become which, and what happens to a value the new kind has no field for, is on the engine's [Change the kind](/docs/engine/annotations#change-the-kind). ## Delete an annotation ```ts await annotation.delete(ref); ``` Deleting an annotation also deletes its popup and its replies, as other PDF apps do. ## Change the drawing order Annotations on a page are drawn in order, and the last one is on top. `reorder()` moves annotations together, in the order you pass them, next to another annotation of the page or to the back or the front: ```ts await annotation.reorder([ref], 'start'); // to the back await annotation.reorder([ref], 'end'); // to the front await annotation.reorder([ref], { after: other }); // just above another annotation ``` Form fields are drawn above every annotation and keep their own order, so `reorder()` never places an annotation above a field. > **Try it:** send the green rectangle to the back, then select another and bring it to the > front. ## Changes show at once A change shows the moment you make it. The engine saves it in the background, and your `await` resolves once it has. Until then the annotation is **pending**: ```ts annotation.isPending(ref); // true while the engine is still saving a change to it ``` You rarely need this: `get()` and `list()` already show the change. It's useful for a small "saving…" hint. If the engine refuses a change (a lock set by someone else, or permission taken away), the change disappears again, and an event says why: The `await` of the call that made the change rejects with the same error. ## Copy an annotation `duplicate()` makes copies of annotations in the same document. It is one change, and one step to undo: ```ts // beside the original, 10 points right and down await annotation.duplicate([ref], { offset: { x: 10, y: 10 } }); // onto another page, at the same spot await annotation.duplicate([ref], { page: otherPage.ref }); ``` > **Try it:** copy the rectangle, then copy the copy: it moves a page further each time. Select the > circle to copy it instead. The copies show at once, and the promise resolves `{ annotations, dropped }`: the copies as the engine wrote them, in the order you named the originals, and [what it left out](#what-a-copy-cant-carry). What a copy is: - **It carries** the original's shape, style, text, flags and link. A stamp keeps its drawing and an attachment its file, with nothing to download. - **It is new.** It has its own ref and a fresh name (`nm`), you are its author, and its dates are today's. - **It moves** by `offset`, in page points. With `page` it goes to that page, at the same spot from the page's top-left. - **Copies keep the links between them.** Copy a whole group and the copies are a group of their own. A link to an annotation you didn't copy is left out. - **Replies don't come.** They are about the original. Only the annotations you name are copied. | Option | What it does | Default | | :------- | :----------------------------------------------------------- | :----------------- | | `page` | The page the copies go on, as a ref or an index. | each on its own | | `offset` | How far each copy moves: `{ x, y }` in page points. | `{ x: 0, y: 0 }` | | `select` | Selects the copies as they show. | `false` | `canDuplicate(refs)` says whether the user may copy them, for a button. For the selection there is `selection.duplicate()`; see [Duplicate the selection](selecting#duplicate-the-selection). To copy into **another document**, use [export and import](saving#export-and-import). A read passed to `create()` isn't a copy: it writes that data as it is, its name included. ## Methods What `useAnnotation()` gives you directly. Its parts have their own pages: `selection`, `draft` and `text` are on [Selecting & editing](selecting#methods), `tools` and `stamps` on [Tools & defaults](tools#methods), and `comments` on [Comments & replies](comments#methods). | Method | What it does | | :------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get(ref)` | One annotation as it shows now, pending changes included, or `null` | | `list({ pages?, subtype? })` | Every annotation in drawing order, or the ones on some pages or of one kind. In a component, use `useAnnotationList(filter)`. [Read annotations](#read-annotations) | | `getAt(page, point)` | The topmost annotation at a point on a page, or `null`. A selected annotation's handles count as the annotation. | | `isPending(ref)` | Whether the engine is still saving a change to it. [Changes show at once](#changes-show-at-once) | | `create(page, fields, resources?, { tool?, select? })` | Creates an annotation from its kind and fields, and shows it at once. A stamp's drawing or an attachment's file goes in `resources`, as `{ appearance }` or `{ file }`. Resolves `{ annotation }`. [Create an annotation](#create-an-annotation) | | `createFromSelection(tool, { clear? })` | Turns the selected text into a highlight, an underline, a strikeout or a squiggly line, one per page. Resolves `{ annotations }`. [From the selected text](#from-the-selected-text) | | `update(ref, changes, resources?)` | Changes only the fields you pass, and `null` removes one. New `resources` replace a stamp's drawing or an attachment's file. Resolves `{ annotation }`. [Change an annotation](#change-an-annotation) | | `delete(ref)` | Deletes an annotation, with its popup and its replies. [Delete an annotation](#delete-an-annotation) | | `reorder(refs, position)` | Moves annotations to a new place in their page's drawing order: next to another annotation, or to the back or front. [Change the drawing order](#change-the-drawing-order) | | `duplicate(refs, { page?, offset?, select? })` | Copies annotations in this document, as one step to undo. Resolves `{ annotations, dropped }`. [Copy an annotation](#copy-an-annotation) | | `canDuplicate(refs)` | Whether the user may copy these annotations: false without the right to create, and for a locked one | | `export({ refs?, pages? })`, `import(bundle, options?)` | Takes annotations out as a bundle, with the bytes they carry, or puts a bundle in, as one step to undo. `import` resolves `{ annotations, refMap, dropped }`. [Export and import](saving#export-and-import) | | `downloadResource(ref, role)` | Downloads a stamp's drawing (`'appearance'`) or an attachment's file (`'file'`), as bytes `create()` takes. A copy needs neither. | | `links.get(ref)`, `links.set(ref, target)`, `links.clear(ref)` | Where an annotation links to, such as a page or a website: read it, set it, or remove the link | | `refresh()` | Reads every annotation from the engine again. Changes arrive by themselves, so you rarely need it. | | `getSettings()`, `updateSettings(changes)`, `resetSettings()` | Reads `snap`, `chrome` and `afterCreate`, changes them while the app runs, or goes back to what you registered. In a component, use `useAnnotationSettings()`. [Settings](../annotations#settings) | | `canRead()`, `canCreate()`, `canUpdate(ref)`, `canDelete(ref)` | Whether the user may see, create, change or delete annotations. The checks that take a `ref` answer for that annotation. [Permissions](#permissions) | Every method that returns a promise also takes a `signal` in its options, to cancel it. ## Permissions | Permission | What it allows | Check | | :------------------- | :----------------- | :-------------------------- | | `doc.annotate.read` | Seeing annotations | `annotation.canRead()` | | `annotations:create` | Creating them | `annotation.canCreate()` | | `annotations:update` | Changing them | `annotation.canUpdate(ref)` | | `annotations:delete` | Deleting them | `annotation.canDelete(ref)` | A permission can end in `:self`, the user's own annotations, or `:group`, their group's. `annotations:update:self` lets someone change what they made and only look at the rest, so the checks that take a `ref` answer per annotation. They also follow the annotation's own flags: for a `locked` one, `canDelete(ref)` is false, so your UI offers no delete button, even though your own code may still delete it (see [Locked annotations](#locked-annotations)). More on [Permissions](../concepts/permissions). ## Good to know ### Locked annotations The `locked` flag stops people from moving, resizing or deleting an annotation, and `lockedContents` stops them from changing its text. These flags are for the people using your app: your own code can still change a locked annotation, as the engine can. To stop the code too, check the flags first. A copy of a locked annotation is locked too. So `canDuplicate()` is false for one: a person could neither move nor delete the copy. Your code can still `duplicate()` it. ### What a copy can't carry A few annotations can't be made again. `duplicate()` leaves them out and lists them in `dropped`, each with its `ref` and a `reason`: - a kind the engine doesn't know (`subtype: 'unsupported'`); - a popup copied without the annotation it shows. Some copies are made without one field, and `dropped` names the `field`: - a link whose action the engine can't create, such as one that runs JavaScript; - a value another app wrote that the engine can't write, such as a beveled border; - a geospatial measure. [Import](saving#export-and-import) leaves the same things out. `create()` with such a read refuses it with `invalid-input`. A form field's box (a widget) belongs to the form, so `duplicate()` doesn't copy one, and `canDuplicate()` is false for it. In [design mode](../forms/building), where the form lends its boxes to this plugin, the whole call is refused with `invalid-input` and nothing is copied. Outside design mode a box isn't one of this plugin's annotations, so the call is refused with `not-found`. To copy boxes, use the form's `duplicateWidgets()` ([Copy fields](../forms/building#copy-fields)), or `selection.duplicate()`, which copies the selected boxes with the annotations. One call copies as much as an [import](saving#export-and-import) brings in: by default 10,000 annotations, with 50 MB of drawings and files between them. Past a limit the call is refused with `invalid-input` and nothing is copied. The engine's [Import & export](/docs/engine/annotations/import-export#limits) page has every limit. ### Changes other people make On a shared document, other people's changes arrive as events and show up in `list()` by themselves. See [Events, saving & sharing](saving).