JDFJDF/ docs

API reference

Programmatic API for the @uurtech/jdf npm package. Use this when you need imperative control: hot-swap documents, react to page changes, or render in-memory documents without a fetch.

npm install @uurtech/jdf

Exports

SymbolWhat
embed(container, url, options?)Fetch + render. Returns a Promise of JDFViewerInstance.
render(container, doc, options?)Render an in-memory JdfDocument. Synchronous.
JDFViewerClass form — new JDFViewer(container, doc, options).
jdf(root?)Manually scan the DOM (or a subtree) for <jdf> tags. Useful for SPAs.
JDFViewerOptionsTypeScript option type.
JDFViewerInstanceTypeScript instance type returned by embed / render.
JdfDocument · Element · PageRe-exported from @jdf/core for convenience.

embed(container, url, options?)

Fetch a .jdf file by URL and render it into the container.

import { embed } from "@uurtech/jdf";
import "@uurtech/jdf/style.css";

const v = await embed("#viewer", "/whitepaper.jdf", {
  zoom: 1.2,
  sidebar: true,
  width: "100%",
  height: "80vh",
  fit: "fit-width",
  onPageChange: (i) => console.log("on page", i),
  onLoad: (doc) => console.log("loaded", doc.meta.title),
  onError: (err) => console.error(err),
});

Container: HTMLElement or a CSS selector string. The element you pass becomes the viewer.

URL: any URL the browser can fetch. CORS must be allowed if cross-origin.

Throws / rejects on fetch errors, invalid JSON, or missing $jdf field. onError is also called.

render(container, doc, options?)

Render an in-memory JdfDocument directly — no network. Synchronous.

import { render, JdfDocument } from "@uurtech/jdf";

const doc: JdfDocument = {
  $jdf: "1.0.0",
  meta: { title: "Generated" },
  pages: [{
    elements: [
      { type: "text", content: "Hello", heading: 1 },
      { type: "text", content: "Generated at runtime" }
    ],
  }],
};

const v = render("#out", doc, { darkMode: "dark" });

Options

FieldTypeDefault
zoomnumber1
sidebarbooleanfalse
toolbarbooleantrue
darkMode"auto" · "light" · "dark""auto"
initialPageinteger (0-based)0
widthnumber (px) or any CSS length—
heightnumber (px) or any CSS length"600px"
fit"manual" · "fit-width" · "fit-page""manual"
onPageChange(pageIndex: number) => void—
onLoad(doc: JdfDocument) => void—
onError(err: Error) => void—

Instance methods

Both embed and render return a JDFViewerInstance:

MethodWhat it does
setZoom(zoom: number)Set zoom level (0.25 – 3).
getZoom(): numberCurrent zoom.
goToPage(idx: number)Scroll to page idx (0-based, clamped).
getCurrentPage(): numberIndex of the most-visible page.
setDocument(doc: JdfDocument)Hot-swap the document, re-render.
destroy()Tear down — clears the container and removes observers.

Class form

For advanced wiring (multiple instances, custom toolbar):

import { JDFViewer } from "@uurtech/jdf";

const el = document.getElementById("v")!;
const v = new JDFViewer(el, doc, { darkMode: "dark" });
// later
v.setDocument(otherDoc);

jdf(root?)

Manually scan a subtree for <jdf> tags. Auto-init runs on DOMContentLoaded + a MutationObserver, so you usually don't need this — but in some SPA frameworks the observer can miss content that mounts during a transition.

import { jdf } from "@uurtech/jdf";

router.afterEach(() => jdf());          // scan whole document
jdf(document.querySelector("#main")); // scan one container

Disabling auto-init

Per element: add manual:

<jdf src="/doc.jdf" manual></jdf>

Globally — set before the script loads:

<script> window.JDFjsAutoInit = false; </script>
<script type="module" src="https://unpkg.com/@uurtech/jdf"></script>

Events

When embed fails, the container fires a custom event you can listen to:

document.querySelector("jdf")!.addEventListener("jdf-error", (e) => {
  console.error("jdf failed:", e.detail);
});