Skip to main content

JavaScript API

The ARender Horizon API is exposed in two ways:

  • On the window object: window.ARender
  • On the element instance: element.ARender, the same object as window.ARender

Only one viewer per page is supported: two <arender-element> tags share one API and one state.

The API exists as soon as the script has loaded, before the viewer has mounted. openDocument can be called straight away: it resolves once the document is displayed. The other commands act on what is open, and refuse with NOT_READY until a document is: await openDocument, or wait for document.changed.

That one viewer can show several panels side by side (multi-view). The API stays one: the document on screen is the document of the active panel, for every command and event that mentions it. See Panels.

Two conventions hold across the API: reads are synchronous, and actions return a promise. Annotation methods are grouped under annotations, because annotations are a collection with symmetric operations (create, read, update, delete); every other command is a single action and sits directly on the root object.

Coming from the Classic viewer's arender.jsapi.*? See Migration from Classic for the concept mapping.

Document reading and navigation​

MethodParametersReturnsDescription
version—stringBuild/app version
openDocument(params)params: stringPromise<void>Opens a document from a query string of parameters. Resolves once the document is displayed. Replaces the whole session: every panel closes and the viewer returns to single view. See Web Component and Opening documents
getCurrentDocumentId()—string | nullThe document on screen — inside a container, the displayed child; in multi-view, the active panel's document. null if nothing is open
getRootDocumentId()—string | nullThe root of the open set, the same for every panel. Equal to the current one on a single document
getDocumentLayout(documentId?)documentId?: stringDocumentLayoutTitle, kind, pages and children of a document. With no argument, answers about the document on screen
getDocumentMetadata(documentId?)documentId?: stringPromise<Record<string, string>>Repository metadata fields for a document. Asynchronous — unlike the other reads, it calls the server
goToPage(page)page: numberPromise<void>Displays a page of the document on screen. 0-based — the viewer's own page field is one higher. In multi-view, only the active panel moves
goToDocument(documentId)documentId: stringPromise<void>Displays a document of the open set, at its first page, in the active panel — even when another panel already displays it
nextDocument() / previousDocument()—Promise<void>Steps to the next/previous document of the open set. Already bound to Ctrl + arrow keys inside the viewer. In multi-view, the active panel steps from its own document

getDocumentLayout() returns:

PropertyTypeDescription
documentIdstring—
titlestring | null—
kind'document' | 'container' | 'video' | 'reference' | 'error''video' has no pages to count; 'reference' is a container child whose own layout hasn't landed yet; an unknown backend type reads as 'document'
pageDimensionsPageDimension[]{width, height, rotation} per page, empty on a container or a failed document
childrenDocumentLayout[]Present on a container only, already resolved — nothing to loop over and refetch
error{code?, message?}Present when this document could not be resolved; its siblings are still listed

goToPage is bounded by the document on screen, not the whole set: inside a container, each document has its own page numbering.

Example: walk a container

const rootId = window.ARender.getRootDocumentId();
const layout = window.ARender.getDocumentLayout(rootId);
for (const child of layout.children ?? []) {
console.log(child.documentId, child.title, child.kind);
}

Panels​

Multi-view shows several documents of the open set side by side, each in its own panel. Single view is one panel. The user opens a panel from a thumbnail ("Open in a new view") or from the "+" between two panels ("Add a view here"), and activates one by clicking in it; a host does the same with these commands.

MethodParametersReturnsDescription
getViews()—View[]The panels, in the order they are displayed: one in single view, none before anything is open. Synchronous
openView(documentId)documentId: stringPromise<number>Opens a panel on a document of the open set, at its first page, after the last panel, and makes it active — what "Open in a new view" does on a thumbnail. Resolves with its viewId. A document already displayed can be opened again, and there is no maximum number of panels
activateView(viewId)viewId: numberPromise<void>Makes a panel the active one, as a click in it does. The document on screen becomes its document
closeView(viewId)viewId: numberPromise<void>Closes a panel, as its close button does. When it was the active one, the next panel takes over, or the previous one. Down to one panel, the viewer returns to single view. The last panel cannot be closed: openDocument is what replaces it

View:

PropertyTypeDescription
viewIdnumberNames the panel, never its place: it starts at 1, grows with each panel opened and is not reused, so after panel 1 closes, panel 2 is first and is still 2. Numbering starts again with each set openDocument opens
documentIdstringThe document the panel displays
isActivebooleanWhether the document on screen comes from this panel

The order of getViews() is the one on screen at the time of the call, and it can change: identify a panel by its viewId, never by its index.

openView, activateView and closeView refuse with NOT_READY until the viewer has opened the first panel of a set, NOT_FOUND on a document outside the open set or a panel that does not exist, and UNSUPPORTED on a value of the wrong type or on closing the last panel.

Example: compare two documents of a container

const rootId = window.ARender.getRootDocumentId();
const second = window.ARender.getDocumentLayout(rootId).children[1];
const viewId = await window.ARender.openView(second.documentId);
await window.ARender.goToPage(2); // moves the new panel, which is active
await window.ARender.closeView(viewId); // back to single view

Search commands​

MethodParametersReturnsDescription
search(text)text: stringPromise<SearchHandle>Searches every document of the open set — not only the one on screen — and displays the first hit. Hits are displayed in the active panel, which changes document when a hit sits in another one. Plain text only: the Classic viewer's advanced options (case, accent, regex, scope) aren't available

SearchHandle:

MemberTypeDescription
positionnumber1-based position of the hit on screen, 0 when there is none
totalnumberHits across every document of the open set
hasSearchableContentbooleanfalse with total: 0 means there was nothing to read (a scan, a video, a container of them) — a different answer from a term simply absent, which is total: 0 with hasSearchableContent: true
next() / previous()Promise<void>Displays the next/previous hit, changing document when it sits in another one
dispose()voidClears the search and retires the handle, without changing the displayed page. The same exit verb used everywhere else a handle is handed back — see Events

The handle is a remote control on the search on screen, not a receipt for one query: position and total follow whatever was searched last, from here or typed into the search bar. A term typed into the bar does not retire the handle, and next()/previous() carry on with it.

Only a newer search() call retires a handle, once that call resolves. A call still in flight, or one that fails, leaves it live. From then on, next() and previous() on the earlier handle reject with STALE_HANDLE, and its dispose() does nothing, so it cannot clear the newer search.

Example

const hits = await window.ARender.search("signature");
if (hits.total === 0) {
console.log(hits.hasSearchableContent ? "not found" : "nothing to read here");
}
await hits.next();
hits.dispose();

Download​

MethodParametersReturnsDescription
download(options?)options?: DownloadOptionsPromise<void>Hands the open document to the user, as the viewer's own download button does

DownloadOptions — the defaults are not neutral: a bare download() gives a PDF of the document on screen, with its annotations, kept editable.

OptionValuesDefaultDescription
format'pdf' | 'original''pdf' where a rendered copy exists'original' is the only variant that works on audio/video or a document the viewer couldn't render; it falls back to PDF on an annotated or redacted document
annotations'editable' | 'flatten' | 'none''editable'Redactions ignore this option — always applied, text removed rather than covered
documents'displayed' | 'all''displayed''displayed' is the document on screen, the active panel's in multi-view. 'all' merges every document of the open set into one PDF, honouring each one's annotations
await window.ARender.download(); // PDF, annotated, editable
await window.ARender.download({ format: "original" }); // the source file
await window.ARender.download({ format: "pdf", documents: "all" }); // one merged PDF

Resolves once the file has been handed to the browser. A download already running is not queued — the call resolves without starting a second one.

Annotations​

window.ARender.annotations covers the annotations of the documents displayed in a panel. An annotation belongs to its document, not to a panel: a command given no document acts on the document on screen, and one given a document acts on it as long as a panel displays it.

Every command writes to the server as it is made — there is no save call and no draft to flush. A command whose write fails rejects with the code of the server's answer, SERVER_ERROR in most cases — see Errors. A write the user made in the viewer has no promise to reject: it is reported by the annotations.writeFailed event instead.

MethodParametersReturnsDescription
create(annotation)annotation: AnnotationInputPromise<string>Places an annotation, returns its identifier. On the document on screen, or on the one annotation.documentId names
update(id, changes)id: string, changes: Partial<AnnotationInput>Promise<void>Changes an annotation by identifier — only the given fields move. The identifier is looked up on every document displayed in a panel
delete(id)id: stringPromise<void>Removes an annotation by identifier, looked up on every document displayed in a panel
get(page?)page?: numberAnnotation[]Reads what the document on screen currently carries, or one page of it (0-based). Synchronous
get(query)query: AnnotationQueryAnnotation[]Reads what a document displayed in a panel currently carries, or one page of it. Synchronous
refresh(documentId?)documentId?: stringPromise<void>Brings in annotations another system wrote through the Rendition REST API while the document was open. Adds rather than replaces — a failed write stays visible, an edit in progress survives. Reads any document of the open set, displayed or not; the annotation events report what it brings in only on a document a panel displays

AnnotationQuery (passed to get):

FieldTypeDescription
documentId?stringAny document displayed in a panel. Defaults to the document on screen
page?number0-based. Omit it for every page

get({documentId}) reads every page of a document, get({documentId, page: 0}) its first page. get refuses with UNSUPPORTED anything that is neither a page nor a query — null and a bare document id included — and a page that is not a whole number.

When the other system writes to a document inside a container, its REST route writes the child identifier with @ in place of / — POST /documents/b64_xxxx@1/annotations, not b64_xxxx%2F1. refresh() takes the identifier as getCurrentDocumentId() gives it, with its /.

AnnotationInput (passed to create):

FieldTypeDescription
documentId?stringAny document displayed in a panel. Defaults to the document on screen. Refused with NOT_FOUND when no panel displays it
pagenumber0-based
type'highlight' | 'square' | 'circle'Only these three today — more annotation types are coming
x, y, width, heightnumberPosition/size in the page's own coordinate space — see Coordinates
color?string#rrggbb, rgb(), hsl() or a colour name: '#ffff00', 'rgb(255, 255, 0)', 'hsl(60, 100%, 50%)', 'yellow'. An alpha channel is ignored — use opacity. Anything else is refused with UNSUPPORTED, including transparent, currentcolor, oklch(), lab() and color(). Defaults to the viewer's own default for that type. Read back as #rrggbb
opacity?number0 to 1. Defaults to the viewer's own default for that type
contents?stringText attached to the annotation

update takes the same shape minus type (immutable once created) and documentId (an annotation does not move to another document), every field optional.

update and delete act on the types create can place — highlight, square and circle — and refuse any other with UNSUPPORTED. Reading is not restricted.

An Annotation read back (from get() or an event) adds: id, documentId, creator (null unless written by another system), and reads type as a plain string — wider than CreatableAnnotationType, since reading is not restricted.

Coordinates​

The same convention holds for every position of the API, read or written:

  • Unit: the page's own size, as getDocumentLayout().pageDimensions gives it — 612 × 792 for a Letter PDF page. It does not change with the zoom or the window size.
  • Origin: the top-left corner of the page. x grows to the right, y grows downwards.
  • {x: width / 2, y: height / 2, width: width / 2, height: height / 2} is therefore the bottom-right quarter of the page.

Example

const id = await window.ARender.annotations.create({
page: 0,
type: "highlight",
x: 100,
y: 200,
width: 150,
height: 20,
color: "#FFEB3B",
opacity: 0.5,
});
await window.ARender.annotations.update(id, { contents: "Check this clause" });
const onPage0 = window.ARender.annotations.get(0);
await window.ARender.annotations.delete(id);

Example: annotate the document of a panel that is not active

const other = window.ARender.getViews().find((view) => !view.isActive);
await window.ARender.annotations.create({
documentId: other.documentId,
page: 0,
type: "square",
x: 50,
y: 50,
width: 100,
height: 60,
});
const onOther = window.ARender.annotations.get({ documentId: other.documentId });

Events​

MethodDescription
on(event, handler)Subscribes handler to event. Returns a Disposable; call .dispose() to unsubscribe
off(event, handler?)Unsubscribes handler from event. Without handler, removes every handler for that event

Subscribing the same function to the same event twice creates two independent subscriptions — each has its own Disposable, so disposing one leaves the other active. off(event, handler), by contrast, matches by function identity and removes every subscription of that function at once, not just the first. A bind()-wrapped function detaches nothing, since binding produces a new function identity. A handler that throws is reported and does not stop the others.

Every subscribable event:

EventPayloadFires
page.changed{page, pageCount, documentId, viewId}Once when a document opens, then once per page the viewer lands on — never once per page crossed on the way. Also when another document is displayed, even at the same page number. Follows the active panel: it also fires when another panel becomes active, with that panel's viewId. A panel that is not active emits nothing, even when it is scrolled
document.changed{documentId, title, viewId}The document on screen changed — inside a container, a different child is displayed. Follows the active panel: it also fires when the panel that becomes active displays another document than the previous one
document.loadFailed{code, message}A document could not be opened; the one on screen is left alone. Reports the request of openDocument or of the document attribute, which no panel owns. A document that fails inside a panel is read through getDocumentLayout().kind
document.firstPageDisplayed{documentId, duration}The first page of a document appeared, duration in milliseconds from the request. Once per document opened. Displaying a document in another panel is not an open, and does not fire it
view.opened{viewId, documentId}A panel was opened, by the user or by openView. Not fired for the first panel of a set: that panel comes with the set openDocument opens
view.closed{viewId}A panel was closed, by the user or by closeView. Exiting multi-view fires it once per panel closed. Opening another set with openDocument does not fire it
annotations.created{annotation}An annotation was drawn or created, once it is stored
annotations.updated{annotation}An annotation was changed — by the user or by annotations.update. Fires as the viewer displays the change, before the server confirms it; a change that then cannot be stored is reported by annotations.writeFailed (user) or a rejected update (host)
annotations.deleted{id, documentId}An annotation was removed — by the user or by annotations.delete, once the server has removed it
annotations.writeFailed{annotation, reason}A write the user made in the viewer could not be stored. Once per annotation. reason is for a log, not for branching

The annotation events cover every document displayed in a panel, the active one or not: an annotation written in a panel the user is not on is reported when it happens. A document displayed in two panels reports each change once. They carry no viewId: an annotation belongs to its document.

Names follow noun.pastVerb: a command is imperative, an event is past tense, so no name ever means both "do it" and "it happened".

Example

const sub = window.ARender.on("page.changed", (e) => {
console.log("panel", e.viewId, "page", e.page, "of", e.pageCount);
});
// later
sub.dispose();

TypeScript​

The arender-ui package ships an ambient arender.d.ts declaring the full ARender.Api namespace, so window.ARender and element.ARender are typed without an import. See Web Component — TypeScript.

Errors​

Every rejected command shares the same shape: a standard Error with a name of 'ARenderError' and a code a host branches on — never on message, whose wording can change.

try {
await window.ARender.goToPage(999);
} catch (err) {
if (window.ARender.isError(err)) {
console.log(err.code, err.message);
}
}
CodeMeaning
NOT_READYNothing is open, its layout has not arrived yet, or its first panel is not open yet
NOT_FOUNDThe identifier given (document, annotation, panel) is not part of the open set, or not displayed in a panel where the command needs it
OUT_OF_RANGEA page or document position outside what exists
UNSUPPORTEDA value outside what the command accepts — unknown format, unlisted annotation type
STALE_HANDLEA handle (search, open) another call has since replaced
SERVER_ERRORThe request failed — the server answered with an error, or could not be reached
FORBIDDENThe server refused the request (HTTP 401 or 403). No command checks a user's rights on its own yet

A command that reaches the server takes its code from the server's answer: NOT_FOUND on a 404, FORBIDDEN on a 401 or 403, UNSUPPORTED on a 415 or 422, and SERVER_ERROR on any other failure or when the server cannot be reached. This holds for openDocument, the annotation writes, annotations.refresh and download, and document.loadFailed carries the same code. getDocumentMetadata always rejects with SERVER_ERROR.

isError() is the only supported way to narrow a caught value (typed unknown) down to code.