Skip to content

Config Options

Jump to bottom
Jones edited this page Jun 24, 2026 · 1 revision

Mango IIIF Viewer - Configuration Options Reference

This document describes the complete set of configuration options available for the Mango IIIF Viewer. Configuration values can be passed either as a JSON-LD object to the config property of the Svelte <Viewer> component, or as a JSON string to the custom element's config attribute:

<!-- Custom Element Usage -->
<mango-viewer config='{"theme": "dark", "showTools": true}'></mango-viewer>

1. General Config Options

Property Type Default Description
language string 'en' Active language code for translations (e.g. 'en', 'fr', 'es', 'cy').
theme 'light' | 'dark' | string 'dark' Visual layout theme.
allowCreateMode boolean false If true, enables authoring tools for annotations and storytelling features.
showThumbnails boolean true Show/hide the horizontal thumbnail strip.
showMetadata boolean true Show/hide the metadata/details panel.
showSearch boolean true Show/hide the search interface.
showAnnotations boolean true Show/hide the annotation panel.
showTools boolean false Show/hide zoom and orientation tools.
showLayers boolean false Show/hide choice layer controls (for multi-image canvases).
showSettings boolean true Show/hide the settings button in the toolbar.
plugins Record<string, unknown> {} Key-value settings passed directly to active plugins.

2. Sidebar Configuration (sidebar)

Allows configuring the layout and defaults of the sidebar drawer panel.

Property Type Default Description
sidebar.open boolean true If false, the sidebar starts collapsed on initialization.
sidebar.activePanel string 'metadata' The panel ID that is active by default. Allowed values: 'metadata', 'search', 'annotations', 'tools', 'contents', 'settings', 'layers'.
sidebar.position 'left' | 'right' 'left' The placement of the sidebar in the viewer layout.

3. Initial View State Parameters

These parameters set the default page number, zoom coordinate, rotation, and layouts on load. Note that URL query/hash parameters (such as #cv=X, #r=X, and #xywh=...) will always override these values if present.

Property Type Default Description
initialCanvasIndex number 0 Zero-based page/canvas index to load on startup.
initialLayoutMode 'single' | 'two-page' | 'continuous' | 'gallery' 'single' Active page presentation layout mode.
initialRotation number 0 Initial viewport rotation angle in degrees (e.g. 0, 90, 180, 270).
initialViewBox object null Initial zoom coordinate box. Format: { x: number, y: number, w: number, h: number }.

4. OpenSeadragon Settings (osd & osdConfig)

Mango exposes both structured high-level toggles and raw pass-through configs.

High-Level Config (osd)

Property Type Default Description
osd.preserveViewport boolean false If true, maintains zoom level/pan position when changing canvases.
osd.showNavigator boolean false Show/hide the picture-in-picture navigator window.
osd.showRotationControl boolean false Show/hide rotation buttons on the viewport.
osd.clickToZoomEnabled boolean true Toggle double-click to zoom behavior.

Raw Pass-Through (osdConfig)

Exposes direct access to any option supported by the native OpenSeadragon constructor (e.g., gestures, animations, performance settings). Element boundaries and tile sources are managed by Mango and will be ignored.

"osdConfig": {
  "visibilityRatio": 0.5,
  "blendingTime": 0.1,
  "zoomPerScroll": 1.5,
  "gestureSettingsTouch": {
    "pinchToZoom": true
  }
}

5. 3D Model Renderer Configuration (modelConfig)

Passes raw HTML attributes directly to the <model-viewer> element for 3D GLB/GLTF rendering.

"modelConfig": {
  "auto-rotate": true,
  "shadow-intensity": 1.5,
  "camera-orbit": "45deg 55deg 2.5m",
  "exposure": 1.2
}

6. PDF Renderer Configuration (pdf)

Sets properties specific to the PDF document renderer.

Property Type Default Description
pdf.page number 1 One-based index of the default page to display when opening a PDF.

7. Storytelling Configuration (story)

Configures storytelling navigation, narration timelines, and saving behavior.

Property Type Default Description
story.enabled boolean false Enable/disable storytelling overlays and panels.
story.showDebug boolean false Enable coordinate guidelines and boundary boxes in the builder.
story.languages string[] ['en'] List of languages supported inside story translations.
story.save.enabled boolean false Enable saving modifications back to a server.
story.save.endpoint string "" Server route endpoint where the payload JSON will be posted.
story.save.method 'POST' | 'PUT' 'POST' The HTTP request method.
story.save.headers Record<string, string> {} Custom authentication or payload headers.
story.save.timeoutMs number 10000 Saved request timeout threshold.
story.save.credentials RequestCredentials 'same-origin' Request credentials policy (e.g. 'same-origin', 'include', 'omit').

8. Complete Example JSON Configuration

{
  "language": "fr",
  "theme": "dark",
  "allowCreateMode": false,
  "showTools": true,
  "sidebar": {
    "open": true,
    "activePanel": "annotations",
    "position": "left"
  },
  "initialCanvasIndex": 2,
  "initialLayoutMode": "two-page",
  "initialRotation": 90,
  "osd": {
    "preserveViewport": true,
    "showNavigator": true
  },
  "osdConfig": {
    "visibilityRatio": 0.8,
    "zoomPerScroll": 1.2
  },
  "modelConfig": {
    "auto-rotate": true,
    "interaction-prompt": "none"
  },
  "pdf": {
    "page": 3
  },
  "story": {
    "enabled": true,
    "languages": ["en", "fr"],
    "save": {
      "enabled": true,
      "endpoint": "https://example.com/api/stories",
      "method": "PUT",
      "headers": {
        "Authorization": "Bearer token123"
      }
    }
  }
}

Clone this wiki locally