Diva.js is a web viewer for IIIF manifests and collections. It combines a document-style scrolling interface with OpenSeadragon-based zooming, collection browsing, table-of-contents navigation, and support for multiple images on a canvas.
- Website: https://diva.simssa.ca/
- Documentation: https://diva.simssa.ca/docs/
- Getting started: https://diva.simssa.ca/docs/getting-started/
- npm package: https://www.npmjs.com/package/diva.js
- GitHub repository: https://github.com/DDMAL/diva.js
Include OpenSeadragon and Diva.js in your page:
<script src="https://cdn.jsdelivr.net/npm/openseadragon@6.0.2/build/openseadragon/openseadragon.min.js"></script>
<script src="path/to/diva.js"></script>Create a container and initialize the viewer with a IIIF manifest or collection URL:
<div id="diva-wrapper"></div>
<script>
const viewer = new Diva("diva-wrapper", {
objectData: "https://example.org/iiif/manifest.json"
});
</script>Give the container a height so the viewer can render correctly:
#diva-wrapper {
display: flex;
width: 100%;
height: 80vh;
}All CSS and image assets are bundled into the built library.
npm install diva.jsThe package publishes browser and ESM builds. For detailed integration guidance, configuration options, and examples, use the documentation site:
Wait for the initial IIIF resource before reading page state or issuing viewer commands:
const viewer = new Diva("diva-wrapper", { objectData: manifestUrl });
await viewer.ready;
const pages = viewer.getPages();
const current = viewer.getCurrentPage();
console.log(current?.canvasId, current?.primaryImage.id);Navigation follows the current layout, so next() and previous() advance by an opening in a spread layout:
await viewer.setLayoutMode("spread");
await viewer.next();
viewer.addEventListener("pagechange", (event) => {
console.log(event.detail.pageIndex, event.detail.visiblePages);
});Set enableAnnotations: true to load manifest annotations. User selection is
enabled by default; enableAnnotationSelection: false disables opening details
by clicking or keyboard activation.
The inspector displays all textual bodies from IIIF v2 resource and v3 body
arrays in source order. HTML fragments are sanitized separately, explicit
text/plain bodies remain literal text, and language/direction metadata is
preserved. Hover tooltips show a concise preview with paragraph and line breaks;
click the annotation outline (not the moving hover preview), or focus it and
press Enter, to read the complete body. getAnnotationBody(id) returns
their source values joined by blank lines, not sanitized inspector HTML.
Diva leaves browser URL and history ownership to the host application: it does not read or write
window.location or listen for hashchange. One useful convention is a p hash parameter with
canvas:, label:, or one-based page: values. Always construct such hashes with
URLSearchParams so identifiers and labels are encoded safely.
function pageTargetFromHash(hash) {
const value = new URLSearchParams(hash.slice(1)).get("p");
if (value?.startsWith("canvas:")) {
return { by: "canvasId", value: value.slice("canvas:".length) };
}
if (value?.startsWith("label:")) {
return { by: "label", value: value.slice("label:".length) };
}
if (value?.startsWith("page:")) {
const pageNumber = Number(value.slice("page:".length));
return Number.isInteger(pageNumber) && pageNumber > 0 ? pageNumber - 1 : undefined;
}
return undefined;
}
const initialPage = pageTargetFromHash(location.hash);
const viewer = new Diva("diva-wrapper", { objectData: manifestUrl, initialPage });
// Example when creating a link:
const hash = new URLSearchParams({ p: `canvas:${canvasId}` });
history.replaceState(null, "", `#${hash}`);Numeric Diva API indexes are zero-based; only the documented page: URL convention is one-based.
Invalid or unmatched initial targets fall back to index 0. Applications can also control later
navigation explicitly. Canvas IDs match exactly; labels match the complete localized display label
case-insensitively, with the first manifest page winning when labels are duplicated.
const page = viewer.findPage({ by: "label", value: "Folio 12r" });
if (page) {
await viewer.goToPage({ by: "canvasId", value: page.canvasId });
}Image regions use full-resolution image pixels with their origin at the upper-left corner. Diva handles navigation, authorization, and waiting for the OpenSeadragon item:
await viewer.zoomToRegion(12, {
x: 840,
y: 1250,
width: 460,
height: 180
}, { padding: 0.08 });Replace the current manifest or collection without replacing the Diva instance or its event listeners, and destroy the viewer when it is no longer needed:
await viewer.setResource(nextManifestUrl);
viewer.destroy();The ESM build exports Diva as both its default and named export, along with the public TypeScript types. OpenSeadragon objects, Elm ports, authentication state, and tile-loading internals are not public API.
The TSDoc comments on the exported TypeScript class and types are the canonical public API documentation. Generate the searchable TypeDoc site with:
yarn docsOpen build/docs/index.html to browse the generated reference. The generated site is a build artifact and is not committed.
Documentation completeness is enforced with:
yarn docs:checkThis command fails when an exported class, constructor, interface, type, property, method, nested event field, or API link is undocumented or invalid.
- IIIF Presentation API v2 and v3 support
- Manifest and collection viewing
- Range-based table of contents navigation
- Multiple image choices per canvas
- OpenSeadragon-powered zooming and panning
Diva is tested against OpenSeadragon 5.0.1 and 6.0.2. The browser regression suite runs the same authorization, loading, and lifecycle scenarios against both versions using local npm packages.
The main viewer can display a nearby page's thumbnail beneath arriving image tiles, then hide it when the visible image has loaded. This reuses thumbnail authorization policies and does not change OSD's full-resolution tile requests. When annotations are enabled, their data is requested in the same preview band; outlines appear once the page's image coordinates are available. Pages without a usable thumbnail continue loading normally. A full-size static image is not fetched solely to provide a preview.
This preview implementation is awaiting manual acceptance before any separate
direction-aware prefetch work; see
browser-tests/PAGE_PREVIEW_ACCEPTANCE.md.
Set showLogoutButton: false in the Diva constructor options to hide the viewer's
IIIF image-service logout controls when the host site provides its own logout
interface. The default is true; hiding the button does not disable authentication
or log the user out.
Diva supports the IIIF Authorization Flow API 2.0 external and active access profiles, including optional logout services. When both profiles are available, Diva first attempts the silent external flow and falls back to the interactive active flow when external authorization does not provide a usable token. Logging out clears the associated local access tokens and re-resolves affected images anonymously. The kiosk profile, redirects, substitutes, and tiered access are intentionally unsupported.
Static image resources use anonymous CORS by default so their pixels remain available to Page View filters and Save view. Set staticImageCorsPolicy: "fallback" to retry a failed static-image request once without CORS, or "none" to use non-CORS loading immediately. Non-CORS static images remain viewable, but their pixels cannot be filtered or saved because the browser taints their canvas. GitHub issue #564 describes this compatibility case.
Build the production bundles:
make buildServe the repo locally for testing:
python3 -m http.server 8000Then open http://localhost:8000/testing/index.html or
http://localhost:8000/testing/testing.html. Both pages use the locally
installed OpenSeadragon 6.0.2 by default; append ?osd=5 to use 5.0.1. The
simple viewer also accepts a URL-encoded manifest query parameter.
Run the local OpenSeadragon matrix with:
yarn test:browser