Getting Started

Install Diva.js

Diva.js requires OpenSeadragon. You can load both browser bundles directly:

<script src="https://cdn.jsdelivr.net/npm/openseadragon@6.0.2/build/openseadragon/openseadragon.min.js"></script>
<script src="path/to/diva.js"></script>

All Diva.js CSS and images are included in its bundle, so there is nothing else to load.

For an application built with npm:

npm install diva.js openseadragon

The package includes browser and ES module builds plus TypeScript declarations. OpenSeadragon must be available globally before a viewer is created:

import OpenSeadragon from "openseadragon";
import Diva from "diva.js";

globalThis.OpenSeadragon = OpenSeadragon;

Create a Viewer

Add a container and create a viewer with a IIIF manifest or collection URL:

<div id="diva-wrapper"></div>

<script>
  const viewer = new Diva("diva-wrapper", {
    objectData: "https://example.org/manifest.json"
  });
</script>

Give the container an explicit height so the viewer can render correctly:

#diva-wrapper {
  display: flex;
  width: 100%;
  height: 80vh;
}

Wait for the initial IIIF resource before reading page state or issuing commands:

await viewer.ready;

const pages = viewer.getPages();
const currentPage = viewer.getCurrentPage();

await viewer.next();

See the API reference for navigation, state, events, resource replacement, region zooming, and lifecycle methods.

Configuration Options

The Diva constructor accepts a root element ID and an options object:

const viewer = new Diva(rootElementId, options);

Option	Type	Default	Description
`objectData`	`string`	required	URL to a IIIF manifest or collection
`initialPage`	`number \| DivaPageSelector`	`0`	Initial zero-based page index, exact canvas ID, or complete case-insensitive label
`acceptHeaders`	`string[]`	`[]`	Preferred HTTP Accept values for IIIF resource requests
`showSidebar`	`boolean`	`true`	Whether to show the navigation sidebar
`sidebarWidth`	`number`	`320`	Initial sidebar width, constrained to 220–520 CSS pixels
`sidebarPanel`	`"thumbnails" \| "contents" \| "metadata"`	`"thumbnails"`	Initially selected available sidebar panel
`showTitle`	`boolean`	`true`	Whether to show the resource title
`setLanguage`	`string`	browser language	Preferred interface language

Page selectors use either an exact canvas identifier or a complete localized label:

const viewer = new Diva("diva-wrapper", {
  objectData: manifestUrl,
  initialPage: { by: "label", value: "Folio 12r" },
  sidebarPanel: "contents",
  sidebarWidth: 360
});

setLanguage should normally be the language subtag of a BCP 47 language tag. For example, use ar for ar-Latn and fr for fr-CA.

IIIF and Image Access

Diva.js supports:

IIIF Presentation API 2 and 3 manifests, collections, ranges, and multiple images per canvas.
IIIF Image API 1, 2, and 3 services.
Static image resources when the image server permits cross-origin canvas access.
The IIIF Authorization Flow API 2.0 active access profile, including optional logout services.

Static images and tiles must return an appropriate CORS header. Diva.js intentionally does not use a non-CORS fallback because its image-processing tools require canvas access.

Authorization API 2.0 kiosk and external profiles, Authentication API 1.0, substitutes, and tiered access are not currently supported.