Initialize the Viewer

Create the viewer with a host element, then wait for both viewer.mount() and viewer.ready() before opening a document or enabling document controls. SDK 2.2.1 adds optional readiness timeout and cancellation controls; existing await viewer.ready() usage remains valid.

import { createViewer } from "@rasterex/viewer";

const viewer = createViewer({ container: "#viewer" });

await viewer.mount();
await viewer.ready();

Pass timeoutMs to override the 60-second default readiness timeout. If Canvas does not become ready in time, the promise rejects with CANVAS_READY_TIMEOUT.

Pass an AbortSignal through signal to cancel readiness. A cancelled readiness promise rejects with VIEWER_NOT_READY. Both options can be used together, and they affect NPM SDK readiness only; no Canvas-side change is required.

• timeoutMs is optional. The default is 60_000 milliseconds.
• signal is optional and accepts an AbortSignal.
• await viewer.ready() without options remains supported.

await viewer.ready({
  timeoutMs: 30_000,
});

const controller = new AbortController();
const readyPromise = viewer.ready({
  signal: controller.signal,
});

controller.abort();

try {
  await readyPromise;
} catch (error) {
  // Cancellation rejects with VIEWER_NOT_READY.
  console.error(error);
}

Subscribe before calling viewer.documents.open(...). Show the progress bar while the request is pending. fileReady is the authoritative confirmation that the file is open and active; hide the progress bar only then. fileLoadFailed is the Canvas-side failure path: hide the progress bar, retain the input, and present a retry action.

const cleanups = [
  viewer.documents.on("fileReady", () => {
    setFileLoading(false);
    setStatus("File ready");
    setDocumentControlsEnabled(true);
  }),
  viewer.documents.on("fileLoadFailed", () => {
    setFileLoading(false);
    setStatus("File could not be loaded. Check the URL and try again.");
    setDocumentControlsEnabled(false);
  })
];

function setFileLoading(isLoading: boolean) {
  document.querySelector("#file-progress")?.toggleAttribute("hidden", !isLoading);
}

function setStatus(message: string) {
  const status = document.querySelector("#file-status");
  if (status) status.textContent = message;
}

function setDocumentControlsEnabled(enabled: boolean) {
  document.querySelectorAll<HTMLButtonElement>("[data-requires-file]").forEach((control) => {
    control.disabled = !enabled;
  });
}

Start the pending UI before the call. The open(...) promise provides the request result, while fileReady and fileLoadFailed keep the host UI synchronized with Canvas file state.

async function openDocument(url: string, displayName: string) {
  setFileLoading(true);
  setStatus("Opening file");
  setDocumentControlsEnabled(false);

  try {
    await viewer.documents.open({ url, displayName });
  } catch (error) {
    setFileLoading(false);
    setStatus(error instanceof Error ? error.message : "File could not be opened");
  }
}

Call every unsubscribe function and destroy the viewer when the host route or component unmounts. This prevents a previous route from changing the current route’s loading state.

function disposeViewer() {
  for (const cleanup of cleanups) cleanup();
  viewer.destroy();
}