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.

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

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

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

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();
}