Viewer API

The small cross-format surface for opening, locating, observing, and releasing documents.

Stable surface

ts
interface DocViewKitViewerElement extends HTMLElement {
  open(source: File | Blob | ArrayBuffer | Uint8Array): Promise<DocumentInfo>;
  reveal(target: ViewerTarget): Promise<RevealResult>;
  close(): Promise<void>;
  destroy(): void;
  readonly state: Readonly<ViewerState>;
}

The API uses capability-driven targets instead of separate navigation methods for pages, slides, and worksheets. Framework adapters remain thin wrappers around this element.

Events

EventWhen to use it
docviewkit-readyAssets and runtime are ready for a document.
docviewkit-statechangeNavigation, selection, or capability state changed.
docviewkit-diagnosticA bounded, approximate, omitted, or blocked path was observed.
docviewkit-errorOpening or rendering cannot continue.
Do not infer support from file extensions

Use DocumentInfo capabilities and structured diagnostics. A file opening successfully is not proof that every authored feature was rendered.

Add a text watermark

ts
viewer.config = {
  ...viewer.config,
  watermark: 'Confidential'
};

await viewer.open(file);

The optional 1–256 character watermark is painted into Viewer pages, thumbnails, and print output without modifying the source document, object list, search results, hit testing, or source mapping. Viewer Commercial, SDK, Enterprise, and Evaluation licenses enable this option; unlicensed sessions and Viewer sessions on the Free plan ignore it. Engine integrations can set the same watermark field after passing the existing Engine license gate.

Customization boundary

ts
viewer.config = {
  ...viewer.config,
  features: {
    ...viewer.config.features,
    interactionModeSwitcher: true, // false by default
    print: true,
    fullscreen: true
  }
};

The Viewer can expose object location, display-only, and text selection as one segmented toolbar control. The switcher is hidden by default; print and fullscreen remain independently configurable, and hidden controls do not leave empty toolbar separators.

  • Design tokens control color, typography, spacing, radius, and surface treatment.
  • Stable ::part hooks expose bounded regions such as the toolbar and search panel.
  • A small slot set supports host actions and business panels.
  • Applications that replace the information architecture should use DocViewKit SDK Engine APIs.