Class Diva

constructor

• new Diva(rootId: string, flags: DivaOptions): Diva

  Create a Diva viewer in an existing root element.

  Parameters

  • rootId: string

    HTML id of the root element, without a leading #.

  • flags: DivaOptions

    Initial resource and display options.

  Returns Diva

  Throws

  Error Thrown synchronously when no element has the supplied rootId.

  Remarks

  Constructing another Diva instance for the same root destroys the previous instance first.

Readonlyready

addEventListener

• addEventListener<K extends keyof DivaEventMap>(
      type: K,
      listener: (this: Diva, event: DivaEventMap[K]) => any,
      options?: boolean | AddEventListenerOptions,
  ): void

  Register a listener for a typed Diva event.

  Type Parameters

  • K extends keyof DivaEventMap

  Parameters

  • type: K

    Event name from DivaEventMap.

  • listener: (this: Diva, event: DivaEventMap[K]) => any

    Callback invoked with the event's typed CustomEvent.

  • Optionaloptions: boolean | AddEventListenerOptions

    Standard DOM listener options.

  Returns void

• addEventListener(
      type: string,
      listener: EventListenerOrEventListenerObject | null,
      options?: boolean | AddEventListenerOptions,
  ): void

  Register a listener for a typed Diva event.

  Parameters

  • type: string

    Event name from DivaEventMap.

  • listener: EventListenerOrEventListenerObject | null

    Callback invoked with the event's typed CustomEvent.

  • Optionaloptions: boolean | AddEventListenerOptions

    Standard DOM listener options.

  Returns void

removeEventListener

• removeEventListener<K extends keyof DivaEventMap>(
      type: K,
      listener: (this: Diva, event: DivaEventMap[K]) => any,
      options?: boolean | EventListenerOptions,
  ): void

  Remove a previously registered Diva event listener.

  Type Parameters

  • K extends keyof DivaEventMap

  Parameters

  • type: K

    Event name from DivaEventMap.

  • listener: (this: Diva, event: DivaEventMap[K]) => any

    Callback originally passed to Diva.addEventListener.

  • Optionaloptions: boolean | EventListenerOptions

    Standard DOM listener options used for matching.

  Returns void

• removeEventListener(
      type: string,
      listener: EventListenerOrEventListenerObject | null,
      options?: boolean | EventListenerOptions,
  ): void

  Remove a previously registered Diva event listener.

  Parameters

  • type: string

    Event name from DivaEventMap.

  • listener: EventListenerOrEventListenerObject | null

    Callback originally passed to Diva.addEventListener.

  • Optionaloptions: boolean | EventListenerOptions

    Standard DOM listener options used for matching.

  Returns void

getState

• getState(): Readonly<DivaState>

  Return a defensive snapshot of current viewer state.

  Returns Readonly<DivaState>

  State that callers may retain without observing later mutations.

getPages

• getPages(): readonly DivaPage[]

  Return defensive metadata snapshots for every displayed page.

  Returns readonly DivaPage[]

  Pages in zero-based display order. Auth tokens and resolved loading URLs are never included.

findPage

• findPage(selector: DivaPageSelector): DivaPage | undefined

  Find a displayed page by Canvas identifier or localized display label.

  Parameters

  • selector: DivaPageSelector

    Exact Canvas-ID or complete label lookup.

  Returns DivaPage | undefined

  A defensive page snapshot, or undefined when no page matches.

  Throws

  TypeError Thrown when a runtime value is not a valid DivaPageSelector.

  Remarks

  Canvas IDs are case-sensitive. Labels are case-insensitive but are not trimmed, whitespace-normalized, or substring-matched. Duplicate labels return the first page in manifest order.

getCurrentPage

• getCurrentPage(): DivaPage | undefined

  Return metadata for the active page, if the resource has pages.

  Returns DivaPage | undefined

  The active page, or undefined before page initialization and for collections without an active manifest.

getVisiblePages

• getVisiblePages(): readonly DivaPage[]

  Return the pages in the active row or opening.

  Returns readonly DivaPage[]

  One page in single mode, or the pages belonging to the current logical opening in a spread mode.

getLayoutMode

• getLayoutMode(): DivaLayoutMode

  Return the current single-page or spread layout mode.

  Returns DivaLayoutMode

  The active DivaLayoutMode.

setResource

• setResource(url: string): Promise<void>

  Replace the current IIIF manifest or collection without replacing this instance.

  Parameters

  • url: string

    URL of a IIIF Presentation manifest or collection.

  Returns Promise<void>

  A promise that resolves when the replacement and its first displayable page are ready.

  Throws

  TypeError Rejected when url is empty.

  Throws

  DOMException Rejected with AbortError when superseded by a newer replacement, or with InvalidStateError when the viewer has been destroyed.

  Remarks

  Event listeners remain attached. Fetching or parsing failures leave the previous resource active. Once a replacement parses, it becomes active; failure of its required image rejects while leaving that replacement and its unavailable-image UI in place. Calling this method before any resource is ready supersedes the constructor resource and determines the outcome of Diva.ready.

  Example

  await viewer.setResource("https://example.org/iiif/next-manifest.json");
  Copy

goToPage

• goToPage(index: number): Promise<void>

  Navigate to a zero-based page index.

  Parameters

  • index: number

    Target index in Diva.getPages.

  Returns Promise<void>

  A promise that resolves after the navigation command is accepted.

  Throws

  RangeError Rejected when index is not an available integer page index.

  Throws

  DOMException Rejected with InvalidStateError after destruction.

• goToPage(selector: DivaPageSelector): Promise<boolean>

  Navigate to a page selected by Canvas identifier or display label.

  Parameters

  • selector: DivaPageSelector

    Page lookup using the matching rules from Diva.findPage.

  Returns Promise<boolean>

  true after navigation, or false without moving when no page matches.

  Throws

  TypeError Rejected when a runtime selector object is malformed.

next

• next(): Promise<void>

  Navigate to the next page or opening for the active layout.

  Returns Promise<void>

  A promise that resolves after navigation, or immediately at the final opening.

  Remarks

  Spread modes advance by logical opening; clients do not need to calculate a page step.

previous

• previous(): Promise<void>

  Navigate to the previous page or opening for the active layout.

  Returns Promise<void>

  A promise that resolves after navigation, or immediately at the first opening.

setZoom

• setZoom(zoom: number): Promise<void>

  Set the OpenSeadragon viewport zoom to a positive value.

  Parameters

  • zoom: number

    Positive finite viewport zoom value.

  Returns Promise<void>

  A promise that resolves after the zoom command is applied.

  Throws

  RangeError Rejected when zoom is not positive and finite.

zoomBy

• zoomBy(factor: number): Promise<void>

  Multiply the current viewport zoom by a positive factor.

  Parameters

  • factor: number

    Positive finite multiplier; values above 1 zoom in and values below 1 zoom out.

  Returns Promise<void>

  A promise that resolves after the zoom command is applied.

  Throws

  RangeError Rejected when factor is not positive and finite.

zoomIn

• zoomIn(): Promise<void>

  Zoom in by Diva's standard zoom factor.

  Returns Promise<void>

  A promise that resolves after multiplying the zoom by 1.6.

zoomOut

• zoomOut(): Promise<void>

  Zoom out by Diva's standard zoom factor.

  Returns Promise<void>

  A promise that resolves after dividing the zoom by 1.6.

fitToPage

• fitToPage(pageIndex?: number): Promise<void>

  Fit a page, or the current page when omitted, into the viewport.

  Parameters

  • OptionalpageIndex: number

    Optional zero-based page index. Defaults to the active page.

  Returns Promise<void>

  A promise that resolves after the page image loads and is fitted.

  Throws

  RangeError Rejected when there is no active page or pageIndex is unavailable.

zoomToRegion

• zoomToRegion(
      pageIndex: number,
      region: DivaRegion,
      options?: ZoomToRegionOptions,
  ): Promise<void>

  Frame a full-resolution pixel rectangle on a page, waiting for that image when necessary.

  Parameters

  • pageIndex: number

    Zero-based page index containing the region.

  • region: DivaRegion

    Rectangle in full-resolution image pixels from the upper-left origin.

  • Optionaloptions: ZoomToRegionOptions

    Optional padding and animation settings.

  Returns Promise<void>

  A promise that resolves after the image loads and the viewport fits the region.

  Throws

  RangeError Rejected for an unavailable page, negative coordinates, non-positive dimensions, non-finite values, or negative padding.

  Throws

  Error Rejected when authorization or image loading fails.

  Example

  await viewer.zoomToRegion(
    12,
    { x: 840, y: 1250, width: 460, height: 180 },
    { padding: 0.08 }
  );
  Copy

setLayoutMode

• setLayoutMode(mode: DivaLayoutMode): Promise<void>

  Change the page layout while preserving the active page.

  Parameters

  • mode: DivaLayoutMode

    Desired single-page or spread arrangement.

  Returns Promise<void>

  A promise that resolves after the layout is applied.

  Throws

  RangeError Rejected for a value outside DivaLayoutMode.

enterFullscreen

• enterFullscreen(): Promise<void>

  Request fullscreen display; browser user-activation rules apply.

  Returns Promise<void>

  A promise that resolves when the root enters fullscreen or is already fullscreen.

  Throws

  DOMException Rejected when browser permissions or user-activation rules deny the request, or with InvalidStateError after destruction.

exitFullscreen

• exitFullscreen(): Promise<void>

  Exit fullscreen display when active.

  Returns Promise<void>

  A promise that resolves when fullscreen exits or when it was already inactive.

  Throws

  DOMException Rejected when the browser cannot exit fullscreen or with InvalidStateError after destruction.

toggleFullscreen

• toggleFullscreen(): Promise<void>

  Enter or exit fullscreen display; browser user-activation rules apply.

  Returns Promise<void>

  The promise returned by Diva.enterFullscreen or Diva.exitFullscreen.

destroy

• destroy(): void

  Cancel outstanding work, release resources, and empty the viewer root.

  Returns void

  Remarks

  Destruction is idempotent and permanent. Pending public commands reject with InvalidStateError; later commands do the same. State snapshots remain readable.