Events & errors
Subscribe to the SDK viewer's events with viewer.on(...), and branch on typed ViewerError codes rather than message strings.
The viewer tells you when things change, and fails with codes, not strings.
In short viewer.on(event, listener) subscribes to loaded,
pageChanged, zoomChanged, scrollChanged, and error, and returns an
unsubscribe function — call it on teardown. Failures surface as a typed
ViewerError carrying a stable code (e.g. GPU_UNAVAILABLE), so you branch on
the code, never on the human-readable message.
Subscribing
const off = viewer.on('pageChanged', ({ page }) => updatePager(page));
// …later
off(); // unsubscribe
viewer.on('error', (err) => {
if (err.code === 'GPU_UNAVAILABLE') showFallback();
});You can see these fire live in the camera & navigation playground — the right-hand panel logs each event as you drive the viewer.
Events
| Member | Signature | Description |
|---|---|---|
| Viewer.on | on<K extends keyof ViewerEvents>(event: K, listener: (payload: ViewerEvents[K]) => void): () => void | Subscribe to a viewer event. Returns a disposer that removes the listener. |
| loaded | loaded: { pageCount: number } | Fired once a document has loaded and laid out. |
| pageChanged | pageChanged: { page: number } | Fired when the current page changes (via goToPage or scrolling). |
| zoomChanged | zoomChanged: { zoom: number } | Fired when the zoom factor changes. |
| scrollChanged | scrollChanged: { x: number; y: number } | Fired when the scroll offset changes. |
| error | error: ViewerError | Fired on a recoverable viewer error. |
Errors
| Member | Signature | Description |
|---|---|---|
| ViewerError | class ViewerError extends Error { code: ViewerErrorCode } | Thrown by createViewer/load and emitted on `error`. Inspect `code` rather than the message. |
| ViewerErrorCode | type ViewerErrorCode = 'GPU_UNAVAILABLE' | 'LOAD_FAILED' | 'RENDER_FAILED' | … | Stable machine-readable error codes — branch on these (e.g. GPU_UNAVAILABLE → show a no-WebGPU fallback). |
Branching on code keeps your handling stable across releases — the message text
may change for clarity, but the codes are part of the contract. The most common
one to handle is GPU_UNAVAILABLE: the viewer is WebGPU-only, so on a browser
without it you show a fallback rather than a blank canvas. See the
embedding guide for the full requirements.
Frequently asked questions
Do I need to unsubscribe?
Yes — on returns a disposer; call it when your component unmounts so listeners
don't accumulate across viewer lifetimes.
Why branch on code instead of the message?
Messages are for humans and may be reworded; ViewerErrorCode values are stable
and meant for control flow.
Which event tells me the document is ready?
loaded, which carries { pageCount }. It fires once layout is complete, after
viewer.load(...) resolves.
Camera & navigation
Drive the SDK viewer's camera — zoom, scroll, fit, page navigation, and layout mode — with a live playground that calls each method as you click.
Rendering to pixels
Produce raster output from the SDK without an on-screen canvas — page thumbnails via the Viewer, or full RGBA/PNG rasters via ViewerSession and Inspector.