Web embed SDK
Show PDF files in your web page with PDF Viewer Native’s own engine. The engine runs in the reader’s browser as WebAssembly. There is no client ID, no account, no server and no telemetry: the file goes from your page to the viewer in the same browser tab, and nowhere else.
The JavaScript API follows the Adobe PDF Embed API, so code written for it needs few changes. Status: phase 3, preview (viewing, annotations, forms, saving, and large files by range requests). The API can change before version 1.0.
Examples: full window, sized container, in line, light box, events and APIs, file picker, annotations and saving, forms, large files, React and Angular.
Compared with the Adobe PDF Embed API
| This SDK | Adobe PDF Embed API | |
|---|---|---|
| Credentials | None | A client ID, registered for your domain |
| Where the viewer comes from | Your choice: this site, or your own copy of the files (static files only) | Adobe’s servers |
| Where the PDF is rendered | In the reader’s browser (WebAssembly) | In the reader’s browser |
| Events | Only to the callbacks of your page; nothing is sent anywhere | To your callbacks; optional Adobe Analytics |
| Embed modes | Full window, sized container, in line, light box | The same |
| Annotations, comments, save | Highlight, underline, strike-through, note, free text, ink, rectangle, ellipse, line, arrow, polygon, connected lines (with fill, dash and line endings), standard stamps; annotation manager; XFDF; SAVE_API |
Available, with more types |
| Forms | Fill text, check box, radio, combo and list fields; calculations without JavaScript | Available |
| Licence | MIT, open source | Adobe terms |
Quick start
<div id="viewer" style="height: 600px"></div>
<script src="https://ramanacr.github.io/pdf-viewer/demo/pdfviewer-embed.js"
integrity="sha384-REPLACE_ME" crossorigin="anonymous"></script>
<script>
const view = new PdfViewer.View({ divId: 'viewer' });
view.previewFile(
{ content: { location: { url: '/files/report.pdf' } }, metaData: { fileName: 'report.pdf' } },
{ embedMode: 'SIZED_CONTAINER' });
</script>
As an ES module:
import { View } from 'https://ramanacr.github.io/pdf-viewer/demo/pdfviewer-embed.mjs';
const view = new View({ divId: 'viewer' });
Your page must be served over http or https (not opened as a file:).
From npm, for a bundler:
npm install pdfviewer-embed
import { View } from 'pdfviewer-embed';
const view = new View({ divId: 'viewer' });
The package holds the SDK script only. The viewer comes from this site by default; pass baseUrl
to use your own copy (see Production).
Replace sha384-REPLACE_ME with the current value: copy it from
https://ramanacr.github.io/pdf-viewer/demo/pdfviewer-embed.integrity.json (each deploy writes it).
With integrity, the browser runs the script only when its bytes match the hash. The value changes
when the script changes, and then the old value stops the script from loading: for a page that must
keep working, see Production. For the ES module, import takes no integrity
attribute; an import map
with an integrity entry does, in the browsers that support it.
Host the viewer yourself
The SDK script lives next to the viewer: pdfviewer-embed.js is in the viewer’s folder (/demo/
on this site). To host everything yourself, publish src/PdfViewer.Web
(see its README),
serve the wwwroot folder as static files, set its <base href> to the folder’s path, and load
pdfviewer-embed.js from there. baseUrl is only needed when the script is not in the viewer’s
folder:
new PdfViewer.View({ divId: 'viewer', baseUrl: 'https://cdn.example.com/pdf-viewer/' });
Self-hosted fonts
A PDF often uses fonts that it does not embed. The viewer then draws the text with its own
fonts: Liberation (Latin, Greek, Cyrillic, Hebrew) and Noto (Arabic, Hebrew, Indic scripts,
Sinhala, Thai, math, symbols, and Chinese, Japanese and Korean in slices), all under the SIL
Open Font License 1.1. They are files in the viewer’s fonts/ folder, next to index.html.
- The viewer fetches a font file only when a page needs a character from it. A document that embeds its fonts fetches none.
- Every request goes to the viewer’s own origin, so no font request goes to Google Fonts or to
another third party. The path check in the viewer and in its render worker enforces this
(
EmbedFrame.ParseFontBaseandjs/font-base.js: only a plain absolute path is used). The viewer page’s Content-Security-Policy (connect-src 'self') is extra defence on the main page; a meta Content-Security-Policy does not apply inside the dedicated render worker. - The viewer checks each Noto file against the size and SHA-256 in
fonts/noto/index.json, which must give both for every file. This catches corrupted, partial or mismatched (for example stale cached) copies; it is not protection against tampering, because the index comes from the same origin as the files. A copy that does not match is fetched once more past the browser’s HTTP cache. If that copy does not match either, it is not used, and its text is reported as missing.
When you host the viewer, publish it with the Noto fonts: run eng/webdemo/noto_fonts.py as in
the viewer’s README.
Without them, the viewer still works; only text that needs them is not drawn.
To keep the fonts in another folder of the viewer’s origin (for example one folder shared by
several viewer versions), set fontBaseUrl. The folder must have the same layout as fonts/
(the Liberation files, and noto/ with its index.json):
new PdfViewer.View({
divId: 'viewer',
baseUrl: 'https://pdf.example.com/viewer/2.1/',
fontBaseUrl: 'https://pdf.example.com/shared/pdf-fonts/', // or '/shared/pdf-fonts/'
});
A relative fontBaseUrl is taken from the viewer’s folder. A URL on another origin throws
INVALID_ARGUMENT: the viewer takes only a path on its own origin, and fonts never come from a
third party.
Production
The files on this site change on each deploy, without notice. integrity on the script tag pins
only the SDK script: the viewer that it loads in the frame (index.html, the app and the engine)
is not pinned by it. For production:
- Host a copy of the viewer and the SDK yourself, from a release or a commit that you chose (see Host the viewer yourself). Update it when you decide to.
- Serve the viewer from another origin than your pages, for example
https://pdf.example.comfor pages onhttps://www.example.com(see Same-origin viewer), and setisolation: 'require'. - Send a
frame-ancestorsheader for the viewer (see Who can frame the viewer). - Load the SDK script with
integrity, the hash of your copy.
new PdfViewer.View(options)
| Option | Meaning |
|---|---|
divId |
The id of the element that holds the viewer. Required. |
baseUrl |
Where the viewer files are. Default: the folder of pdfviewer-embed.js. |
fontBaseUrl |
Where the viewer’s bundled fonts are: a folder on the viewer’s own origin. Default: fonts/ next to the viewer. See Self-hosted fonts. |
locale |
Accepted. The viewer is in English only for now. |
isolation |
'warn' (default) or 'require': what to do when the viewer has the same origin as your page. 'warn' writes one console warning; 'require' throws INVALID_ARGUMENT. See Same-origin viewer. |
renderInWorker |
true to draw pages in a Web Worker, so the reader’s main thread stays free; false (default) draws them on the main thread. Preview: see Rendering in a worker. |
view.destroy() removes the viewer from the page (not in the Adobe API).
view.previewFile(file, config)
Returns a Promise. It resolves with a viewer object when the document is open, and rejects with
a PdfViewer.PdfViewerError when it cannot be shown. Call it again to show another file in the
same View.
File
{
content: { location: { url, headers: [{ key, value }], credentials, rangeRequests } } // or
{ promise, linearizationInfo } // promise resolves to an ArrayBuffer, typed array or Blob
{ arrayBuffer }, // an ArrayBuffer, typed array or Blob
metaData: { fileName, id, hasReadOnlyAccess },
}
location. Your page fetches the URL, withfetch, so your page’s own rules apply: the headers you give, cookies for your own site, and the server’s CORS rules for another site. Addcredentials: 'include'tolocationto send cookies to another site. The viewer itself never fetches the file: its Content-Security-Policy allows only its own files. When the server answers range requests, the file is read by ranges (see large files);rangeRequests: falsereads it whole.linearizationInfo(withpromise): read the file by ranges through your own functions, as in Adobe’s API. See large files.promiseandarrayBuffer. The SDK copies the bytes and transfers the copy to the viewer, so your buffer stays usable.metaData.fileNameis shown in the viewer and used for Download and Save.idcomes back ingetPDFMetadata()and astarget.sourceof annotations.hasReadOnlyAccess: trueremoves the annotation tools and form filling; the annotation manager can read, but its changes reject withNOT_ALLOWED.- Largest file: 512 MB. For
location, the SDK counts the bytes as they arrive and stops the download (TOO_LARGE) as soon as there are more; aContent-Lengththat is already too large fails at once. A Blob is checked by its size before it is read.
Config
| Key | Values | Default | Notes |
|---|---|---|---|
embedMode |
FULL_WINDOW, SIZED_CONTAINER, IN_LINE, LIGHT_BOX |
FULL_WINDOW |
See embed modes. |
defaultViewMode |
FIT_WIDTH, FIT_PAGE, TWO_COLUMN, TWO_COLUMN_FIT_PAGE |
FIT_WIDTH |
In line, fit page is fit width. |
showDownloadPDF |
true, false |
true |
Download saves the bytes you gave, or the annotated document with downloadWithAnnotations. |
showPrintPDF |
true, false |
true |
See printing. Disabled when the document forbids printing. |
showZoomControl |
true, false |
true |
|
showBookmarks |
true, false |
true |
The outline tab of the side panel (full window, light box). |
showThumbnails |
true, false |
true |
The pages tab of the side panel (full window, light box). |
showFullScreen |
true, false |
true |
Sized container only. |
showAnnotationTools |
true, false |
true |
The annotation toolbar, in full window and light box. See annotations. |
enableAnnotationAPIs |
true, false |
false |
Needed for getAnnotationManager() and its events. |
includePDFAnnotations |
true, false |
false |
The file’s own annotations of the supported types are listed and can be changed. With false they are drawn but not managed. |
enableFormFilling |
true, false |
true in full window and light box, else false |
See forms. |
downloadWithAnnotations |
true, false |
false |
Download saves the document with the reader’s annotations and form data. |
printWithAnnotations |
true, false |
false |
Print prints the annotations and form data. With false, the file as you gave it. |
focusOnRendering |
true, false |
true for full window and light box |
Moves the keyboard focus to the viewer when the file opens. |
exitPDFViewerType |
CLOSE, RETURN |
CLOSE |
The light box’s button says “Close” or “Return”. |
enableSearchAPIs |
true, false |
false |
Needed for search(). |
theme |
system, light, dark |
system |
The viewer’s colours; pages keep theirs. |
An unknown key is ignored. A known key with a wrong value rejects the Promise with
INVALID_ARGUMENT and a message that names the key.
Embed modes
| Mode | The viewer |
|---|---|
FULL_WINDOW |
Fills the element (give it the size of the page). Full toolbar with the file name, side panel with outline, page thumbnails and search results. |
SIZED_CONTAINER |
Fills an element that you size. Compact toolbar, no side panel, a full-screen button. |
IN_LINE |
Shows every page in the flow of your page. The frame grows to the document’s height and your page scrolls; pages are drawn as they come into view. |
LIGHT_BOX |
Covers your page, with the file name and a Close (or Return) button above it. Escape closes it and gives the focus back. |
Large files
A large file does not have to arrive whole before its first page shows. The viewer asks your page for the byte ranges it needs, as Adobe’s and pdf.js’s viewers do: the end of the file (the cross-reference table), the catalog and the root of the page tree, the tree nodes on the path to page 1, then the objects of each page when it is drawn. The rest of the file follows in the background, one request at a time, after the first page is on screen.
With a URL
view.previewFile({ content: { location: { url: 'https://files.example.com/big.pdf' } }, metaData: { fileName: 'big.pdf' } });
- The SDK asks for one byte (
Range: bytes=0-0). An answer206 Partial ContentwithContent-Range: bytes 0-0/<length>turns range loading on; any other answer is read as the whole file, as before. - It reads the last 1 MB and sends it to the viewer with the open message.
- The viewer asks for ranges with
fetchRangemessages (at most 4 MB each, at most 6 waiting); the SDK fetches them from the URL you gave and no other, with your headers andcredentials, and checks that each answer is206with exactly the bytes asked for.
Files of 1 MB or less are read whole. rangeRequests: false turns range loading off.
Server requirements. One-range requests (Range: bytes=a-b) answered with 206 and
Content-Range, as GitHub Pages, S3, Azure Blob Storage, nginx and Apache do for static files.
The file must not change while it is read (the SDK compares the length in every Content-Range).
For a file on another origin, CORS must allow your page and expose Content-Range:
Access-Control-Allow-Origin: https://www.example.com
Access-Control-Expose-Headers: Content-Range, Accept-Ranges, Content-Length
Range: bytes=a-b is a CORS-safelisted header, so no preflight request is needed. Without the
exposed Content-Range header the SDK cannot read the length and reads the file whole.
Serve PDFs without Content-Encoding: the SDK checks that each answer has exactly the bytes asked for.
With linearizationInfo
As in Adobe’s PDF Embed API, give functions that read the file, for example from your own storage or a service that needs signed requests:
view.previewFile({
content: {
promise: fetchWholeFile(), // used only when the viewer needs the whole file at once
linearizationInfo: {
getInfo: () => Promise.resolve({ fileSize }),
getInitialBuffer: () => readBytes(0, 65535), // optional: the start of the file
getFileBufferRanges: ranges => // [{ start, end }], end inclusive
Promise.all(ranges.map(r => readBytes(r.start, r.end))).then(bufferList => ({ bufferList })),
},
},
metaData: { fileName: 'big.pdf' },
});
getInfo()resolves with{ fileSize }(a whole number of bytes, at most 512 MB).getInitialBuffer(), optional, resolves with the first bytes of the file (anArrayBufferor typed array), or{ buffer, start }for bytes from another offset.getFileBufferRanges(ranges)gets[{ start, end }](endinclusive, as in an HTTPRangeheader) and resolves with{ bufferList: [ArrayBuffer, …] }or an array of buffers, one per range, each exactlyend - start + 1bytes long.content.promiseis read only whenlinearizationInfofails (then the file is read whole from it, as withoutlinearizationInfo). To avoid reading the file twice, give a promise that starts its download only when it is awaited (athen-able object), as the large-file example does.
Only the shape of these functions follows Adobe’s documentation; the details above (end
inclusive, bufferList) are this SDK’s and were not tested against Adobe’s viewer.
While the rest of the file loads
- Pages draw and their text can be selected; scrolling to a page fetches its ranges first.
- Calls that need the whole file wait for it:
getPDFMetadata(),search(), the annotation manager, Download, Save. The annotation tools, form fields and the outline appear when the file is complete. A password-protected file asks for its password as usual. APP_RENDERING_DONE(see events) tells when the first page is on screen and how many bytes the viewer had read by then.
Fallbacks
- A server without range support, an unreadable
Content-Range, or a file of 1 MB or less: the file is read whole, as before. - A damaged file whose cross-reference table must be rebuilt by scanning the whole file: the viewer reads it whole at once, then opens it as usual.
- A page that still needs bytes after its objects were fetched (for example an object the cross-reference table places wrongly): the viewer fetches them and draws the page again; after 12 rounds it reads the whole file.
- A range request that fails (network, HTTP error, timeout after 60 s): at open,
previewFilerejects withNETWORK_ERROR; later, the page is left undrawn (the viewer’s status names the error) and a zoom change draws it again. If the background read of the rest fails, it tries again after 2, 4, 8 and 16 s (when a page is drawn), from where it stopped; after five failures the viewer shows a Try again button. The host page aborts its own fetches after 60 s without an answer, and when the viewer is closed or another file is opened. - An object whose bytes, by the cross-reference table, would pass a cap (one page needs more than 256 MB, the document’s structure or one round of missing bytes more than 32 MB): the cap is checked before the bytes are asked for, and the viewer reads the whole file instead.
- A page tree whose
/Countvalues do not match their kids, that has a loop, or that is too deep to walk lazily (a page not found after 12 rounds): the viewer reads the whole page tree, as before this change, and stays on range requests. If the real page count differs from the root’s/Count, the page list is corrected. - Two files opened one after the other: only the second shows, even when the first finishes last;
the first
previewFilerejects withCLOSED.
How it works
The engine (PdfEngine.Vector, shared with the Windows viewer) reads PDFs through a synchronous
byte source. PdfRangedDocument puts a 4 KB block cache under it (PdfChunkCache, least
recently used first, 64 MB by default, the current page’s blocks always kept; while a document
opens, the cache passes its cap by at most the 32 MB a round may fetch). Before a page is
parsed, PdfRangePlanner walks its objects level by level from the page dictionary (resources,
fonts, images, annotations; not /Parent or links to other pages) and fetches each level’s byte
ranges (an object runs from its cross-reference offset to the next object’s). Then the page is
parsed and drawn synchronously from the cache. A read of a block that is not there records the
miss; the operation is repeated on a fresh parse after the missing bytes arrive. Documents
opened from memory or from a file do not use any of this.
The page tree is lazy (PdfPageTree.IsLazy, PdfRangedOptions.LazyPageTree). The page count is
the root’s /Count, checked against the number of objects in the file before anything is sized
by it. A page is found when it is first needed: from the root, the engine goes down to the kid
whose /Count holds the page, one level per round of requests. A node with one kid per page
goes straight to the kid; in other nodes every kid is read (at most 64 more per round), and the
kids’ pages must add up to the node’s /Count. A loop, a kid listed twice, a tree deeper than
PdfSecurityLimits.MaxPageTreeDepth or a count that does not add up turns the lazy tree off (see
fallbacks). Pages not read yet are laid out at the first page’s size. When a page of another
size is read (before it is drawn) or when the whole file is in, the layout is corrected
(ViewerDocument.PagesChanged). Below a node, the engine checks only the counts on the path to
a page. A wrong /Count in a node beside that path can put pages in the wrong order until the
whole file is read; the viewer then draws again the pages it drew.
Measured
A generated file of 320 pages, each with a 224 × 224 image stored uncompressed (46.2 MB, not
linearized, objects written page by page), served by eng/webdemo/serve.mjs on the same machine,
headless Chrome 155, time from the host page’s start to the first page on screen (it includes the
viewer’s own start, about 1 s), three runs:
| File | Network | Whole file | By ranges | Read before the first page |
|---|---|---|---|---|
| Page objects spread through the file | loopback | 2.4 to 3.1 s | 1.6 to 1.7 s | 1.2 MB (2.5 %), 6 requests |
| The same | 50 Mbit/s, 40 ms (serve.mjs) |
10.7 to 10.9 s | 2.4 to 2.7 s | 1.2 MB (2.5 %), 6 requests |
| The same | 50 Mbit/s, 40 ms (in the page) | 1.5 to 1.6 s | 1.2 MB (2.5 %), 4 requests | |
The same, with object streams (PdfOptimizer) |
loopback | 1.5 to 2.3 s | 1.5 to 2.3 s | 1.2 MB (2.5 %), 5 requests |
| The same, with object streams | 50 Mbit/s, 40 ms | 9.3 to 10.4 s | 2.9 to 3.1 s | 1.2 MB (2.5 %), 5 requests |
Before the lazy page tree, the file with spread-out page objects needed one request per page to
open (2.4 MB in 318 requests): 2.5 to 2.9 s on loopback, 21.4 to 21.6 s at 50 Mbit/s and 40 ms
through serve.mjs (Chrome sent the requests for the same URL almost one at a time), and 5.1
to 5.4 s with the network simulated in the page. Now the first page needs the end of the file,
page 1’s dictionary and page 1’s objects, whatever the number of pages. The object-stream rows
were measured before the change; such files open in a few requests either way. The spread-out
rows were measured on 2026-10-27 with warm browser caches (the viewer itself was not
downloaded again). The large-file example repeats the measurement
in your browser.
Events
The annotation manager has its own events: see annotation events.
view.registerCallback(PdfViewer.View.Enum.CallbackType.EVENT_LISTENER,
event => console.log(event.type, event.data),
{ listenOn: ['PAGE_VIEW', 'TEXT_COPY'] }); // leave listenOn out to hear every event
| Event | data |
When |
|---|---|---|
DOCUMENT_OPEN |
fileName, numPages |
The document is open. |
PAGE_VIEW |
pageNumber |
The current page changes (also once when the document opens). |
ZOOM_CHANGE |
zoom (1 is 100 %) |
The zoom changes, by the reader, an API or a fit. |
TEXT_SEARCH |
searchedText |
A search starts, from the search box or search(). |
TEXT_COPY |
copiedText |
The reader copies selected text (Ctrl+C). |
DOCUMENT_DOWNLOAD |
fileName |
The reader downloads the file. |
DOCUMENT_PRINT |
fileName |
The pages are ready and the print dialog opens. |
PREVIEW_ERROR |
code, message |
previewFile failed (the Promise rejects too). |
APP_RENDERING_DONE |
pageNumber, ms, bytesRead, fileSize, ranged |
The first page of a file is on screen. ms counts from the viewer’s open; bytesRead is what it had read of the file by then. |
Events go only to your callbacks, in your page. enablePDFAnalytics and similar options do not
exist: there is nothing to send events to.
APIs
const viewer = await view.previewFile(file, config);
const apis = await viewer.getAPIs();
Every method returns a Promise.
| Method | Result |
|---|---|
getPDFMetadata() |
{ numPages, pdfTitle, author, subject, keywords, creator, producer, creationDate, modDate, pdfVersion, isEncrypted, isTagged, canCopy, canPrint, wasRepaired, isSigned, certificationLevel, fileSize, fileName, id }. Dates are "YYYY-MM-DDTHH:mm:ss" as written in the file, or null. isSigned is true when the file has a signed signature field or a certification signature; certificationLevel is the certification signature’s DocMDP level (1, 2 or 3), or null. See signed and certified files. |
getCurrentPage() |
The page number. |
gotoLocation(pageNumber, x, y) |
Scrolls the point (x, y) of the page to the top-left of the view. x and y are PDF points from the top-left corner of the page as shown (Adobe’s are from the bottom-left). Both default to 0. |
getSelectedContent() |
{ type: 'text', data }: the selected text, '' when none. Rejects with NOT_ALLOWED when the document forbids copying (see Copy protection). |
getZoomAPIs() |
{ zoomIn(), zoomOut(), setZoomLevel(level), getZoomLimits() }. The first three resolve with the new zoom; the limits are { minZoom: 0.1, maxZoom: 8 }. |
search(term) |
Needs enableSearchAPIs: true. Resolves with a search object: onResultsUpdate(callback), next(), previous(), clear(). Works in documents that forbid copying too (see Copy protection). |
The search callback receives { currentResult: { pageNumber, index }, totalResults, status }.
index counts from 1 over the whole document; status is IN_PROGRESS while pages are read and
COMPLETED after. A new search (from the API or the search box) ends the previous one: its
methods then reject with SEARCH_ENDED.
A viewer object belongs to one document. After previewFile shows another file, its methods
reject with NO_DOCUMENT.
Error codes
Other enums: PdfViewer.View.Enum.CallbackType (EVENT_LISTENER, SAVE_API),
AnnotationEvents, ApiResponseCode (SUCCESS, FAIL).
PdfViewer.View.Enum.ErrorCode: INVALID_ARGUMENT, FILE_NOT_FOUND (HTTP 404 or 410),
HTTP_ERROR (another HTTP error; detail.status), NETWORK_ERROR (the network failed or CORS
does not let your page read the file: browsers do not say which), NOT_A_PDF, TOO_LARGE,
PASSWORD_REQUIRED and WRONG_PASSWORD (the reader closed the password prompt),
CERTIFICATE_REQUIRED, ENCRYPTION_NOT_SUPPORTED, VIEWER_LOAD_FAILED (the viewer did not start
in 60 seconds), NO_DOCUMENT, NOT_ENABLED, NOT_ALLOWED, SEARCH_ENDED, CLOSED (the viewer
was removed or the light box closed), VIEWER_ERROR.
Password-protected files: the viewer asks the reader for the password. Your page never sees it.
Annotations
With showAnnotationTools (full window and light box), a second toolbar shows these tools:
| Tool | How |
|---|---|
| Select | Select text (drag), or click an annotation to select it; drag it to move it; Delete deletes it. Click a selected note, text box or callout to edit its text. A selected callout shows a round handle at the spot it points to: drag it to move that spot. |
| Highlight, underline, strike-through | Drag over text. With text already selected, the button marks it at once. |
| Note | Click where the note goes, then type the comment. |
| Text box (free text) | Click, or drag a box, then type. An empty new text box is not kept. |
| Callout | Click the spot the callout points to, then click or drag where its text box goes, then type. Esc drops the first click. The line has an open arrow at that spot and a knee next to the box, as Acrobat draws one. Drag the box to move it: the spot stays, and the line meets the box again. An empty new callout is not kept. |
| Pen (ink) | Draw with the mouse or a pen. Each stroke is one annotation. |
| Rectangle, ellipse | Drag the shape. |
| Line, arrow | Drag from the start to the end. The arrow has an open arrowhead at its end. |
| Polygon, connected lines | Click each point. Double-click or press Enter to end; Esc cancels. |
| Stamp | Pick a stamp (Approved, Draft, Confidential and the other standard ones) and click where it goes. On a turned page (/Rotate), the stamp reads upright as the page is shown. |
| Custom stamp | In the stamp list, Custom stamp… opens a dialog: choose a PNG or JPEG picture or a PDF (for a PDF, choose the page; a small preview shows it), then Place stamp, then click where it goes (2 inches across its longer side) or drag its box (it keeps its shape). The file is read in the browser and never uploaded. Tick Keep it in this browser’s stamp library to find it in the stamp list again; the dialog lists the saved stamps with a delete button. An embedded viewer has no library: its origin is shared by every host page, so it keeps nothing in the browser. |
The colour buttons set the colour of the next annotation, or change the selected one (a stamp keeps the colour of its kind).
For a rectangle, ellipse, line, arrow, polygon or connected lines, lists next to the colour buttons set the shape style of the next shape of that tool, or change the selected shape:
- Fill (
/IC): none, or one of the toolbar colours. It fills a rectangle, ellipse or polygon, and the closed line endings. A fill from the file that is not in the list shows as “Current fill”. - Line style (
/BSwith/S /Dand/D): solid, dashed ([4 3]) or dotted ([1 2]). Another dash from the file shows as “Current dash”. - Line start and Line end (lines and connected lines,
/LE): the ten endings of ISO 32000-2 Table 179. The arrow tool starts with an open arrow at the end. The shape’s box grows to hold new endings.
Each change is one undo step. A shape from the file keeps its own fill, dash, line endings and
/BS until that value is changed: no defaults are added to it. A measurement (an annotation
with /Measure) shows no shape style and keeps its own. A file’s shape moved to another page
(with updateAnnotation) is written there as a new annotation with its own entries, its
/Measure too. While a list has the focus, it keeps its letters, arrow keys and Delete;
Ctrl+Z and Ctrl+Y still undo and redo. Undo and redo (Ctrl+Z, Ctrl+Y) cover every annotation
change, the host page’s too. The side panel’s Comments tab lists the annotations as
threads: each reply is under the comment it answers. Click one to go to it; with a comment
selected, Reply adds a reply. Deleting a comment deletes its replies, as in Acrobat.
Every change is written into the document by the engine (the same PdfAnnotationEditor as the
Windows viewer): real annotation dictionaries with appearance streams, as an incremental update
of the file you gave. The pages are drawn from that document, so what the reader sees is what
Save writes, and Acrobat and other readers show the same annotations.
The annotation manager
const viewer = await view.previewFile(file, { enableAnnotationAPIs: true, includePDFAnnotations: true });
const manager = await viewer.getAnnotationManager();
getAnnotationManager() rejects with NOT_ENABLED without enableAnnotationAPIs: true. Every
method returns a Promise.
| Method | Result |
|---|---|
addAnnotations(list) |
Adds 1 to 1000 annotations (all or none). Resolves with them as stored: an id is made when you give none, the author and dates are filled in. An id in use rejects. |
getAnnotations(filter?) |
The annotations, all or those of the filter. |
selectAnnotation(id) |
Selects it and scrolls to it; resolves with it. |
unselectAnnotation() |
|
updateAnnotation(annotation) |
Replaces the annotation with the same id (its subtype cannot change); resolves with it. modified becomes now. Without a creator, the annotation keeps the author it has (none stays none). |
deleteAnnotations(filter) |
Deletes the annotations of the filter ({} deletes all); resolves with the deleted ones. |
setConfig(config) |
{ showToolbar, showCommentsPanel, downloadWithAnnotations, printWithAnnotations, authorName }, each optional. authorName is the author of the reader’s new annotations (default Guest). |
exportXfdf() |
The annotations as an XFDF document (ISO 19444-1), a string. |
addCustomStamp(options) |
Adds a custom stamp made from a PNG or JPEG picture or from a page of a PDF; resolves with the annotation. See custom stamps. |
importXfdf(xml) |
Adds the annotations of an XFDF document (the supported types; others are skipped) as one undo step; resolves with the ones added. Long texts are cut to the limits below. An annotation that is not valid here (more than 1000 quadrilaterals, off the document’s pages, outside a page’s media box) is skipped, with its replies, and the viewer’s status line counts the skipped ones. A reply deeper than 64 levels is skipped the same way. The import is rejected as a whole with INVALID_ARGUMENT (a message that starts with importXfdf: ) when the text is not XFDF, when it has more than 1000 annotations to add, or when they would take the document past its limits (10 000 annotations, or the total of points below); then nothing is added. Changed in this version: before, one annotation that was not valid (off the pages, for example) rejected the whole import; now it is skipped and the others are added, as in the Android app. |
registerEventListener(handler, { listenOn }) |
See annotation events. |
A filter is { annotationIds: ['id1', …], pageRange: { startPage, endPage } } (pages from 1),
each part optional. getAnnotations also takes includeCustomStampData: true (see
custom stamps). Changes reject with NOT_ALLOWED when the file was opened with
hasReadOnlyAccess or the document forbids annotations (its permissions, or a
signature), and with INVALID_ARGUMENT (and a message that
says what) for an annotation that is not valid.
Annotation JSON
Close to the Adobe PDF Embed API’s format (W3C Web Annotation style):
{
id: 'b1c3…', // 1 to 200 characters; made when missing
type: 'Annotation',
motivation: 'highlighting', // 'highlighting' for text markup, 'commenting' for the others (written by the viewer)
bodyValue: 'The comment', // the text: note, free text, or the comment of a markup; at most 10 000 characters
target: {
source: 'report-q3', // metaData.id, else the file name (written by the viewer)
selector: {
node: { index: 0 }, // the page, counted from 0
subtype: 'highlight', // highlight, underline, strikeout, note, freetext, ink, square, circle,
// line, polygon, polyline, stamp
boundingBox: [x1, y1, x2, y2], // the annotation's /Rect (a callout's: its text box)
quadPoints: [x1, y1, x2, y2, x3, y3, x4, y4, …], // text markup: 8 numbers per line
inkList: [[x, y, x, y, …], …], // ink: one array per stroke
vertices: [x1, y1, x2, y2, …], // line: its two points (/L); polygon (3 or more), polyline (2 or more): /Vertices
lineEndings: ['None', 'OpenArrow'], // line and polyline: the start and end (/LE, see below)
callout: [x1, y1, x2, y2, x3, y3], // freetext: a callout's line (/CL), the spot it points to first (see below)
calloutEnding: 'OpenArrow', // freetext with callout: the ending at that spot (/LE); default OpenArrow
stampName: 'Approved', // stamp: its /Name (see below)
strokeColor: '#FFD400', // the line colour; the text colour of free text
fillColor: '#CCE5FF', // inside of square, circle and polygon; closed line endings; free text background (optional)
dashPattern: [4, 3], // square, circle, line, polygon, polyline: dash and gap lengths in points (optional, see below)
strokeWidth: 2, // ink, square, circle, line, polygon, polyline, the free text border (0 to 100)
opacity: 1, // 0 to 1
fontSize: 12, // free text, 4 to 144
},
},
creator: { type: 'Person', name: 'Ada' },
created: '2026-10-26T10:00:00Z', // ISO 8601; made when missing
modified: '2026-10-26T10:05:00Z',
}
Coordinates are PDF points in the page’s user space: the origin is the lower-left corner of
the page’s coordinate system (usually the lower-left corner of the page) and y goes up, as in
the PDF file and in Adobe’s API. The page’s /Rotate is not applied. (gotoLocation takes
points from the top-left of the page as shown.) quadPoints give each quadrilateral as
upper-left, upper-right, lower-left, lower-right. For markup, boundingBox can be left out
(the box around quadPoints); for ink too (the box around the strokes), and for lines,
polygons and polylines (the box around vertices, grown to hold the line endings and cut to
the page).
lineEndings are names of ISO 32000-2 Table 179: None, Square, Circle, Diamond,
OpenArrow, ClosedArrow, Butt, ROpenArrow, RClosedArrow, Slash. stampName is one
of Approved, SBCompleted, Confidential, Draft, Final, ForComment, ForPublicRelease,
SBInformationOnly, NotApproved, NotForPublicRelease, SBPreliminaryResults, Received,
SBReviewed, SBRevised, SBVoid, Expired, TopSecret, AsIs, Experimental, Sold,
Departmental; the engine draws the stamp with its label in the colour of its kind.
dashPattern makes the line of a square, circle, line, polygon or polyline dashed (/BS /S /D
with this /D): 1 to 16 numbers from 0 to 1000, not all 0. The toolbar’s presets are [4, 3]
(dashed) and [1, 2] (dotted). The viewer gives it only for a dashed shape, with the file’s
numbers as they are (not rounded).
addAnnotations: leave it out, or givenullor[], for a solid line.updateAnnotation: leave it out to keep the shape’s dash (so a page written beforedashPatternexisted does not change it). Givenullor[]to make the line solid. A dash within 0.1 % of the current one is not a change: a file’s shape then keeps its own/D.updateAnnotationreplaces the other values, so give thefillColorandlineEndingsthat the shape should keep.- A measurement (
/Measure) keeps its fill, dash and line endings: values given for them are ignored, and no error is returned. - A polygon has no line endings:
lineEndingsgiven for one are ignored.
A callout is a freetext annotation with callout (ISO 32000-2 12.5.6.6: /IT /FreeTextCallout,
/CL, /LE and /RD):
{ type: 'Annotation', motivation: 'commenting', bodyValue: 'Check this total',
target: { selector: { node: { index: 0 }, subtype: 'freetext',
boundingBox: [300, 600, 450, 640], // the text box
callout: [120, 700], // the spot it points to: the viewer adds the knee and the end
calloutEnding: 'OpenArrow', strokeColor: '#E5484D', fontSize: 12 } } }
boundingBoxis the text box. The viewer writes the/Rectaround the box and the line, and/RDfor the box inside it, as Acrobat does.calloutis the line:[x, y](only the spot it points to: the viewer lays out a knee and the end on the middle of the box’s side that faces the spot), or the line’s points[x1, y1, x2, y2]or[x1, y1, x2, y2, x3, y3](the spot first, the point on the box last).getAnnotationsalways gives the full line. Every point must be on the page.calloutEndingis one of thelineEndingsnames (defaultOpenArrow).strokeColoris the text, border and line colour;strokeWidth(above 0) the border and line width.updateAnnotationreplaces the whole annotation: givecalloutagain (asgetAnnotationsgives it), or the callout becomes a plain text box. When you moveboundingBoxand give the line back unchanged, the spot it points to stays and the viewer lays out the knee and end again.exportXfdfandimportXfdfkeep callouts as Acrobat writes them:<freetext>withcallout,head,intent="FreeTextCallout"andfringe.
A reply answers another annotation (a note with /IRT, ISO 32000-2 12.5.6.4). It has no
selector: its target is the id of the annotation it answers, and it takes that one’s page:
{ id: 'r1', type: 'Annotation', motivation: 'replying', bodyValue: 'Agreed.',
target: 'b1c3…', creator: { type: 'Person', name: 'Bo' }, created, modified }
A reply can answer a reply, up to 64 levels. What a reply answers cannot change with
updateAnnotation. deleteAnnotations deletes the replies of every annotation it deletes,
and resolves with them too. A reply is written with an empty appearance, so other readers list
it in their comments and do not draw a second note on the page.
A review status is a reply with a status object. The reader sets one in the viewer’s comments panel (select a comment, then pick its status). Acrobat, the desktop app, this viewer and the Android app write a status as a hidden reply with /State and /StateModel (Accepted, Rejected, Cancelled, Completed or None in the Review model):
{ id: 's1', type: 'Annotation', motivation: 'replying', bodyValue: 'Accepted set by Bo',
target: 'b1c3…', status: { state: 'Accepted', stateModel: 'Review' }, creator, created, modified }
getAnnotations returns statuses with their status object. Keep them out of the replies that your page shows. The latest status by created is the comment’s status, and None clears it. Give the status object back unchanged with addAnnotations or updateAnnotation. state and stateModel are each 1 to 64 characters. A status stays a status: updateAnnotation refuses to turn a status into a plain reply, or a reply into a status.
Changed in this version: before, statuses in a file were not read. They now come with their status object.
Every value is checked: types, string lengths, colours (#RRGGBB), finite numbers, and the
geometry: on a page of the document and inside its media box (2 points of tolerance plus the
line width). Limits: 1000 annotations per call, 10 000 per document, 1000 quadrilaterals per
markup, 100 strokes and 10 000 points per stroke (50 000 points) per ink annotation, 10 000
vertices per polygon or polyline, and 1 000 000 ink, quadrilateral and vertex points per
document (a quadrilateral has 4), counted when
annotations are added and when an update makes one larger: past it, INVALID_ARGUMENT. Texts:
bodyValue 10 000 characters, creator.name 256.
XFDF (importXfdf) is read as a stream: no DTD, no external entities, at most 8 MB of text,
100 000 elements and 64 attributes per element (past them, INVALID_ARGUMENT); unknown
elements are skipped without being built. Its texts are cut to the same limits as the
annotation JSON (title, subject and name 256 characters, contents 10 000), so one long field
does not refuse the whole import. A dash pattern must have 1 to 16 numbers, none negative and
not all zero, else it is [3]. Lines, polygons and polylines need finite points (a polygon or
polyline with more than 10 000 vertices is skipped, not cut); a line ending name that is not
in Table 179 is read as None. A reply’s inreplyto names the annotation it answers: one of
the same import (before or after it), else one the document has. A reply whose parent is in
neither, and an annotation with inreplyto that is not a note reply (a group member, for
example), is added on its own. exportXfdf names a parent that has no /NM (obj-<number>),
so its replies keep their thread.
The file’s annotations of these types are managed with includePDFAnnotations (not hidden
ones or other types: links, carets, file attachments, form fields and the like stay as they
are). Replies are managed when they are notes and their /IRT chain reaches a managed
annotation within 64 levels; a chain that loops, a group member (/RT /Group) and a reply of
another type stay as they are. A stamp from the file keeps its own appearance when it is moved.
Their id is their /NM, or pdf-<page>-<index> when they have none. New and changed
annotations are written with /NM set to their id, so ids survive a save.
Custom stamps
A custom stamp is a /Stamp named Custom whose appearance draws a picture or a page of a PDF
as a form XObject, as the desktop app writes one: a PDF page stays vector content, a JPEG is
embedded as it is, and a PNG is embedded losslessly with its transparency. It reads upright on a
turned page, and Acrobat and the desktop app draw it from that appearance.
const response = await fetch('/signature.png');
const stamp = await manager.addCustomStamp({
data: await response.arrayBuffer(), // an ArrayBuffer, a typed array or a Blob: PNG, JPEG or PDF
pageNumber: 1, // the page to stamp, from 1 (default 1; null too)
boundingBox: [72, 72, 216, 144], // optional: the box it is fitted in (PDF points), keeping its shape
sourcePage: 1, // a PDF's page to stamp, from 1 (default 1; null too)
});
// stamp.target.selector: { subtype: 'stamp', stampName: 'Custom', customStamp: true, boundingBox, … }
- Without
boundingBoxthe stamp is centred on the page, 2 inches across its longer side; a box smaller than 8 points either way places it so on the box’s corner. A larger box gets the largest stamp of its shape, centred in it. The stamp is kept on the page. datais checked as untrusted input: at most 20 MB for a PDF and 10 MB for a picture, at most 12 million pixels and 10 000 pixels a side. A picture is decoded (a damaged one is rejected); one of more than 4 million pixels is decoded smaller, keeping its shape. A JPEG that is upright is embedded as it is, without its metadata (EXIF, comments); a JPEG turned by its EXIF orientation is decoded and turned. A PDF that is encrypted, is not a PDF, or has no suchsourcePageis rejected. Only the page’s content and resources are kept: not its annotations, page actions, metadata or the file’s document information. Nothing copied carries an action, a script or a link to another file. A stamp placed many times is one copy in the file. A document’s custom stamps, with those that undo and redo can bring back, hold at most 48 MB together. Each case rejects withINVALID_ARGUMENTand a message.- Bytes beside any other call are dropped, and bytes over 20 MB are not taken.
getAnnotationsgives a custom stamp withsubtype: 'stamp',stampName: 'Custom'andcustomStamp: true(other stamps havecustomStamp: false). It does not give the picture or page unless you ask: withgetAnnotations({ includeCustomStampData: true }), a stamp made in this session also hascustomStampData: { kind: 'image' | 'page', mimeType: 'application/pdf', data },databeing the one-page PDF that draws it, base64. A custom stamp read from the file (customStamp: trueby its name) keeps its appearance and has nocustomStampData.updateAnnotationmoves or resizes it: give it back withstampName: 'Custom'and a newboundingBox. It keeps what it draws, and the box is fitted to its shape (centred in the box given).addAnnotationswithstampName: 'Custom'rejects: a custom stamp comes fromaddCustomStamp. Delete it and undo it as any annotation.- The bytes travel to the viewer’s frame beside the message (transferred, never uploaded).
exportXfdfwrites it as a stamp namedCustomwithout its picture, soimportXfdfskips it.
Annotation events
manager.registerEventListener(event => console.log(event.type, event.data),
{ listenOn: ['ANNOTATION_ADDED', 'ANNOTATION_DELETED'] }); // leave listenOn out to hear all
| Event | When |
|---|---|
ANNOTATION_ADDED |
The reader adds an annotation (or undoes a deletion). |
ANNOTATION_UPDATED |
The reader moves or changes one (colour, text, one point of a line or shape), or undo changes it back. |
ANNOTATION_DELETED |
The reader deletes one (or undoes its addition). |
ANNOTATION_SELECTED, ANNOTATION_UNSELECTED |
The reader selects one, or the selection ends. |
ANNOTATION_CLICKED |
The reader clicks one with the select tool. |
event.data is the annotation (the JSON above). Events report what the reader does; the
manager’s own calls do not fire them, so a page that keeps annotations on its server gets no
echo of its own changes.
Saving (SAVE_API)
view.registerCallback(PdfViewer.View.Enum.CallbackType.SAVE_API,
async (metaData, content, options) => {
await fetch('/api/files/' + metaData.id, { method: 'PUT', body: content }); // your server
return { code: PdfViewer.View.Enum.ApiResponseCode.SUCCESS, data: { metaData } };
},
{ autoSaveFrequency: 0, enableFocusPolling: false, showSaveButton: true });
Register it before previewFile (or after: it applies to the open document). With it, the
viewer shows a Save button (showSaveButton, default true), and saves when the reader
presses it or Ctrl+S, every autoSaveFrequency seconds (0, the default, is never; at most
86400) when something changed, and, with enableFocusPolling: true, when the viewer loses the
focus (the reader goes back to your page) with changes not saved.
metaDatais{ fileName, id }.contentis anArrayBuffer: the PDF with the reader’s annotations and form data, as an incremental update of the file you gave (earlier revisions and their signatures stay as they were). It is transferred to your page, not copied.optionsis{ reason }:button,shortcut,autosaveorfocus.- Resolve with
{ code: 'SUCCESS' }and the viewer shows “Saved” and counts the document as saved (the version it posted: changes made while your callback ran stay unsaved); anything else (FAIL, a throw, a rejection) shows “The file was not saved.” and keeps the changes as unsaved.data.metaData.fileNamerenames the file in the viewer. - One save runs at a time. The button,
Ctrl+S, autosave and focus polling do not start a second one while a save waits for the changes to be written or for your answer, and the SDK calls your callback for one save after another (never two at once), so an older, slower save cannot finish after a newer one. A save stays in flight until your callback answers or the viewer closes: after 120 seconds the viewer only says “Still saving…”. - If the viewer cannot write the reader’s latest changes into the document, it shows an error, keeps the changes as unsaved and does not call your callback: it never posts a file without the changes it shows.
Without a SAVE_API callback, Ctrl+S downloads the annotated document (when
showDownloadPDF is on). Nothing is sent anywhere but to your callback.
Forms
With enableFormFilling (and unless hasReadOnlyAccess), the reader fills the document’s
AcroForm fields: text (single and multi-line, password, maximum length), check boxes, radio
buttons, combo boxes and list boxes. Read-only fields, push buttons and signature fields are
not filled. A value goes to the engine, which writes it with a new appearance and runs the
form’s calculations, formats and validations as the Windows viewer does: the standard Acrobat
functions (AFSimple_Calculate, AFNumber_Format, AFRange_Validate, …) and simplified
field notation are recognised, never run: document JavaScript is never executed. A value
that a validation refuses is not kept, and the viewer says why. Saving (SAVE_API, or Download
with downloadWithAnnotations) writes the values into the PDF. XFA forms are not supported.
Values are checked as the reader enters them: a combo box (unless it is editable) and a list
box take only their options (export value or display text), a text field takes at most its
/MaxLen characters (a single-line field loses line breaks), every value at most 10 000
characters, and at most 10 000 fields change at once. A refused value is not kept, and the viewer
shows why. The web viewer and the Android app check values with the same code (ViewerEditSession).
There is no API to set form values from your page in this version: form fields take the reader’s input only. The saved file (SAVE_API) has the values; read them on your server.
Signed and certified files
The viewer follows Acrobat’s rules for a file with signatures, so that its changes never break them silently:
| The file | Annotations | Form filling |
|---|---|---|
Certified, DocMDP P=1 (no changes) |
No | No |
Certified, P=2 (form filling and signing) |
No | Yes |
Certified, P=3 (also annotations) |
Yes | Yes |
| Signed, not certified | Yes | Yes |
| Signed (or certified) and damaged, so that a save would rewrite the whole file | No | No |
When changes are allowed, the viewer tells the reader once, at the first change, that
changes are added as a new revision: existing signatures stay valid, but they show that the
document was modified after signing. Saves are incremental updates, so the signed bytes stay
as they were (they are a prefix of the saved file). When changes are not allowed, the viewer
says why, the tools stay hidden, and the annotation manager’s changes reject with
NOT_ALLOWED. getPDFMetadata() reports isSigned and certificationLevel. The viewer does
not check signatures (the Windows viewer does).
In the viewer
- Text selection: drag with the mouse or a pen over a page, double-click for a word,
Ctrl+Afor the page,Ctrl+Cto copy. One page at a time. Touch scrolls. - Search with the box in the toolbar, the results in the side panel (full window).
- Thumbnails and the outline in the side panel. Night pages (inverted colours).
- The same engine as the Windows viewer: see the web viewer’s limits (fonts a PDF does not embed, CMYK JPEG images, certificate encryption).
Printing
Print renders every page to a 150 dpi image and prints the images through a hidden frame. The printout is a picture of each page: text is sharp enough to read but not as crisp as a PDF application’s print, and it cannot be selected. Every sheet has the size of the first page. Documents of more than 500 pages are not printed from the browser: download them and print them from a PDF application.
Security and privacy
- Isolation. The viewer runs in an
iframewithsandbox="allow-scripts allow-same-origin allow-downloads allow-modals": scripts (the engine), its own origin (its files and fonts), downloads (Download) and modal dialogs (Print). It cannot navigate your page, open pop-ups or submit forms, as long as it has another origin than your page (see Same-origin viewer). - Messages. The two sides talk only by
postMessage, with a versioned protocol ({ protocol: 'pdfviewer-embed', version: 1, type, ... }):- The SDK accepts messages only from its own frame (
event.source) and the viewer’s origin (event.origin), and posts only to that origin. - The frame’s URL carries your page’s origin (
?embed=1&mode=…&origin=…). The viewer accepts messages only from its parent window and that origin, and posts only to that origin. If another site frames the viewer and names your origin, the browser delivers nothing to it. WithfontBaseUrl, the URL also has&fonts=/path/: the viewer takes it only as a plain absolute path on its own origin (EmbedFrame.ParseFontBase), never as another host. - The viewer checks every message (
EmbedProtocolinsrc/PdfViewer.Web.Engine/Embed, with unit tests): unknown protocols, versions and types are ignored; bad arguments are refused with a code. - The file goes to the viewer as a transferred
ArrayBuffer, and a saved file comes back the same way, only to the SAVE_API callback. - Annotations, filters, XFDF and save results from your page are untrusted data to the viewer: every value is checked for type, length and range (see annotation JSON), and an XFDF document is read as a stream without a DTD or external entities, with element, attribute and length limits.
- A message longer than 2 MB of JSON (the file’s bytes do not count) is refused with
INVALID_ARGUMENTbefore it is parsed. - Range loading (see large files): the viewer lists
rangein thefeaturesof itsreadymessage, and the SDK uses range loading only then. AfetchRangerequest carries only numbers (file,requestId,start,end), never a URL. The SDK serves it only for the file it opened last, only for a new request id, only for whole numbers inside the file withend - startat most 4 MB, and only while fewer than 6 requests wait; it fetches the bytes from the URL orlinearizationInfoyou gave. The viewer checks each answer: the request must be waiting, of that file, with exactly the bytes asked for.
- The SDK accepts messages only from its own frame (
- No storage. The embedded viewer keeps nothing in the browser’s storage (the stand-alone demo keeps its theme and side-panel choice).
- No telemetry, no uploads. The viewer requests only its own files (the app, and fonts when a page needs them). Document JavaScript is never run.
Same-origin viewer
The sandbox of the frame keeps the viewer apart from your page only when the two have different
origins. With allow-scripts allow-same-origin on the same origin, the viewer’s scripts could
reach your page (its DOM, cookies and storage), so a fault in the viewer would be a fault in your
page. The viewer needs both flags: it runs WebAssembly and loads its own files and fonts.
When the viewer has the origin of your page, the SDK writes one warning to the console. The
examples on this site do this: they load the viewer from /pdf-viewer/demo/ on the same origin.
For production, serve the viewer from another origin, for example a subdomain
(https://pdf.example.com for pages on https://www.example.com), and make the SDK refuse a
same-origin viewer:
new PdfViewer.View({ divId: 'viewer', baseUrl: 'https://pdf.example.com/', isolation: 'require' });
With isolation: 'require', the constructor throws a PdfViewerError with the code
INVALID_ARGUMENT when the origins are the same.
Who can frame the viewer
Any site can put the viewer in a frame. The viewer still talks only to the origin that its frame URL names, and the browser delivers its messages only to that origin, so another site gets only the files that it sends itself. But it can show them under the viewer’s address, and it can lay its own content over the frame (clickjacking).
A Content-Security-Policy <meta> tag cannot set frame-ancestors (browsers ignore it there), and
GitHub Pages cannot send response headers. If you host the viewer, send this header with the
viewer’s index.html, and name the sites that may embed it:
Content-Security-Policy: frame-ancestors https://www.example.com https://intranet.example.com
For example, in nginx:
add_header Content-Security-Policy "frame-ancestors https://www.example.com" always;.
The header adds to the <meta> policy of index.html; the browser applies both.
For the public demo on this site, the impact is low: it has no accounts, no cookies and no stored documents, it shows only the files that the embedding page sends, and it is open source, so anyone can host the same viewer anyway.
Copy protection
A PDF can forbid copying its text. In such a document:
getSelectedContent()rejects withNOT_ALLOWED.Ctrl+Ccopies nothing, and noTEXT_COPYevent is sent.- Search still works, from the search box and from
search(), as in Adobe Acrobat, which allows search in copy-protected documents.search()gives your page only page numbers and counts, not the text of the document.
Browser support
Browsers with WebAssembly SIMD and exception handling: current Chrome, Edge, Firefox and Safari. Tested on Chromium (Chrome headless and the Chromium of the Claude desktop app). Firefox and Safari are not tested yet.
Limits
| First load | The viewer is about 5.6 MB with Brotli, about 6.6 MB with gzip (GitHub Pages), then cached by the browser. |
| File size | 512 MB. |
| Pages | Drawn one at a time on the main thread, in strips; a heavy page’s interpretation still blocks the viewer for a moment (see responsiveness). |
| Loading | By ranges when the server allows it (see large files); otherwise the whole file is read before the first page shows. While a ranged file loads, calls that need all of it wait. |
| Selection | One page at a time; dragging does not scroll. |
| Annotations | The types above (callouts and custom stamps too) and replies; no carets, file attachments or reply states (/State) yet; stamps have no handle to resize or turn them in the viewer (the API resizes a custom stamp), and a line or polygon is moved as a whole (its points have no handles yet). Each change writes the document again from the file as opened: on a very large file a change takes a moment. Undo: 100 steps, annotations only (form fields have the browser’s own undo while typing). |
| Forms | AcroForm only (no XFA); no document JavaScript, so custom scripts do nothing; free text and stamps embed the bundled Liberation Sans. No API to set form values from the host page yet. Simplified field notation nested deeper than 64 levels is not calculated. |
| Language | The viewer is in English. |
Responsiveness
Blazor WebAssembly runs .NET on the browser’s main thread, so the work of a page (interpreting its content into a display list, then drawing it with Skia) blocks input while it runs. The viewer keeps scrolling responsive this way:
- Pages are drawn in horizontal strips of about 256 K pixels, with a yield to the browser
between strips (
ViewerDocument.RenderPageInStripsAsync). - A page that leaves the view, or a zoom or night-mode change, stops its remaining strips; the display list stays cached, so the page costs only its drawing when it comes back.
- While the view scrolls, no new page or thumbnail starts; work starts when the view has rested for 120 ms. Pages nearest the current one go first.
Measured in headless Chrome (viewer frame, PerformanceObserver long tasks over 50 ms, while a
script scrolls 350 px every 100 ms for 4 s), 40 generated pages with an image and thousands of
filled rectangles each:
| Pages | Before: long tasks while scrolling | After | Scroll-tick delay, 90th percentile: before → after |
|---|---|---|---|
| 3,000 rectangles (interpret 170 to 370 ms, draw 120 to 230 ms per page) | 13 to 14, 5.7 to 6.1 s in all, longest 0.57 s | 5 to 6, 1.0 to 1.1 s in all, longest 0.44 s | 0.39 to 0.43 s → 0.02 to 0.04 s |
| 15,000 rectangles (interpret 750 to 940 ms, draw 390 to 460 ms) | 12 to 13, 17 to 22 s in all, longest 2.0 s | 6, 2.4 s in all, longest 1.0 s | 1.8 to 1.9 s → 0.03 to 0.04 s |
What remains: the interpretation of one page is one task (here up to 1 s), when it runs.
Not possible on GitHub Pages (or any host that cannot send headers):
- .NET multithreading (
WasmEnableThreads, still experimental in .NET 9) needsSharedArrayBuffer, so the page must be cross-origin isolated with the response headersCross-Origin-Opener-Policy: same-originandCross-Origin-Embedder-Policy: require-corp. GitHub Pages cannot send response headers, and an embedded viewer would also need the host page to be isolated (or to frame it withallow="cross-origin-isolated"). - A second .NET runtime in a Web Worker needs no headers. The viewer has one, as an option: see the next section.
Rendering in a worker
With renderInWorker: true (or index.html?renderInWorker=1 for the viewer on its own), the
pages in view are interpreted and drawn by a second, render-only .NET runtime in a dedicated Web
Worker. The viewer’s own runtime keeps the text, search, selection, annotations, forms,
thumbnails and printing.
const view = new PdfViewer.View({ divId: 'viewer', renderInWorker: true });
- Measured in headless Chrome, engine tour, zoom and scroll: total blocking time 110 to 188 ms on the main thread, 0 ms with the worker; the longest gap of a 10 ms timer 166 to 244 ms, against 16 to 22 ms. The time to the first page is about the same.
- Cost: the worker requests the runtime’s files a second time (from the HTTP cache when the server allows caching) and holds a second copy of the runtime and of the document in memory.
- Scope: the worker draws complete, unencrypted files with the bundled fonts. Files still loading by ranges, encrypted files and fonts lent by the host are drawn on the main thread.
- Fallback: while the worker starts, and when it fails, stops answering or cannot draw a page, the pages are drawn on the main thread as without the option.
- Checked in Chrome and Firefox on Windows; not yet in Safari or on a phone, so it is off by default.
Planned
- Rendering in a worker by default, once it is checked in Safari and on phones.
- Later: handles for the points of lines and polygons, reply states (accepted, rejected), and handles to resize and turn stamps.