This web component displays IIIF images using the OpenSeadragon library. It is intended to be used in the Edirom Online, but can also be (re-)used in other web applications. No compilation or building is necessary to use the web component.
Note: This repository only contains the bare JavaScript-based component. There is a separate demo suite for web components developed in the Edirom Online Reloaded project, where the component can be seen and tested.
- IIIF Support: Load IIIF manifests or direct tile sources
- Image Navigation: Navigate through multi-page image sequences
- Zoom & Pan: Interactive zoom and pan controls
- Rotation: Rotate images to any angle
- Customizable Controls: Show/hide navigator, zoom buttons, home button, fullscreen toggle
- Attribute-Driven: All interactions through standard HTML attributes
- Custom Configuration: Pass advanced OpenSeadragon options via JSON
- Event Communication: Custom events for state changes
The edirom-image-viewer.js comes with the MIT license.
The imported OpenSeadragon library comes with the BSD-3-Clause license.
Add the web component script to your HTML page's <head>:
<script src="https://cdn.jsdelivr.net/npm/openseadragon@4.1.1/build/openseadragon/openseadragon.min.js"></script>
<script src="path/to/edirom-image-viewer.js"></script>Include the custom element in your HTML <body>:
<edirom-openseadragon
tilesources='["https://example.com/iiif/manifest.json"]'
shownavigator="true"
showzoomcontrol="true"
sequencemode="true">
</edirom-openseadragon>Control the component by setting attributes programmatically:
const viewer = document.querySelector('edirom-openseadragon');
viewer.setAttribute('zoom', '2.5');
viewer.setAttribute('rotation', '90');
viewer.setAttribute('pagenumber', '5');The component fires custom events when state changes:
viewer.addEventListener('communicate-zoom-update', (event) => {
console.log('Zoom changed:', event.detail);
});Note: All attribute values are strings. The data type information indicates the expected format.
Important Note on Page Numbering: Page numbers are 1-based for user-facing interactions. This means:
- Page 1 = First image
- Page 2 = Second image
- And so on...
This applies to pagenumber attribute and all page-related methods. The component automatically converts between 1-based (user) and 0-based (internal) indexing.
| Attribute | Type | Description | Default |
|---|---|---|---|
tilesources |
string | JSON array of IIIF manifest URLs or tile source URLs. Example: '["https://example.com/manifest.json"]' or '["https://example.com/info.json"]' |
"" |
pagenumber |
number | Current page number in a multi-image sequence (1-based, where 1 = first image). | 1 |
zoom |
number | Zoom level of the viewer. | 1 |
rotation |
number | Rotation angle in degrees (0-360). | 0 |
clicktozoom |
boolean | Enable click-to-zoom functionality. | true |
shownavigationcontrol |
boolean | Show/hide all navigation controls. | true |
sequencemode |
boolean | Enable sequence mode for multi-image navigation. | false |
shownavigator |
boolean | Show/hide the navigator mini-map. | true |
showzoomcontrol |
boolean | Show/hide zoom in/out buttons. | true |
showhomecontrol |
boolean | Show/hide the home/reset view button. | true |
showfullpagecontrol |
boolean | Show/hide the fullscreen toggle button. | true |
showsequencecontrol |
boolean | Show/hide previous/next page buttons (requires sequencemode="true"). |
true |
triggerhome |
boolean | Trigger home position reset (set to "true" to reset view to initial state). |
"false" |
triggerfullscreen |
boolean | Trigger fullscreen mode toggle (set to "true" to toggle fullscreen). |
"false" |
openseadragon-options |
string | JSON object with additional OpenSeadragon configuration options. Example: '{"showNavigator": true}' |
"" |
The component provides the following public methods:
nextPage()- Navigate to the next pagepreviousPage()- Navigate to the previous pagegoToPage(pageNumber)- Navigate to a specific pagegetCurrentPage()- Get the current page numbergetTotalPages()- Get the total number of pages
zoomIn()- Zoom in by 20%zoomOut()- Zoom out by 20%setZoom(level)- Set zoom to a specific levelgetZoom()- Get the current zoom level
home()- Reset view to initial statesetFullScreen(fullScreen)- Set fullscreen mode (true/false)toggleFullScreen()- Toggle fullscreen modeisFullScreen()- Check if in fullscreen mode
rotate(degrees)- Rotate by specified degrees (relative)setRotation(degrees)- Set rotation to specific angle (absolute)getRotation()- Get current rotation angle
<edirom-openseadragon
tilesources='["https://example.com/iiif/manifest.json"]'>
</edirom-openseadragon><edirom-openseadragon
id="viewer"
tilesources='["https://content.staatsbibliothek-berlin.de/dc/69007087X-0001/info.json", "https://content.staatsbibliothek-berlin.de/dc/69007087X-0002/info.json"]'
pagenumber="1"
zoom="1"
rotation="0"
triggerhome="false"
triggerfullscreen="false"
sequencemode="true"
showsequencecontrol="true"
shownavigator="true"
showzoomcontrol="true"
showhomecontrol="true"
showfullpagecontrol="true">
</edirom-openseadragon>const viewer = document.querySelector('edirom-openseadragon');
// Navigate to page 3
viewer.setAttribute('pagenumber', '3');
// Zoom to level 2
viewer.setAttribute('zoom', '2');
// Reset to home position
viewer.setAttribute('triggerhome', 'true');
// Toggle fullscreen
viewer.setAttribute('triggerfullscreen', 'true');
The component supports both IIIF manifests and direct image tile sources:
- IIIF Manifests: Automatically fetches and parses IIIF Presentation API manifests to extract image URLs
- Direct Tile Sources: Use IIIF Image API info.json URLs directly
Trigger attributes are used to invoke actions on the viewer. Set these attributes to "true" to trigger the corresponding action:
triggerhome: Reset view to initial/home positiontriggerfullscreen: Toggle fullscreen mode on/off
Example:
const viewer = document.querySelector('edirom-openseadragon');
viewer.setAttribute('triggerhome', 'true'); // Reset to home position
viewer.setAttribute('triggerfullscreen', 'true'); // Toggle fullscreenThe component fires custom events when attributes change:
communicate-zoom-update- Fired when zoom level changescommunicate-rotation-update- Fired when rotation changescommunicate-pagenumber-update- Fired when page changescommunicate-triggerhome-update- Fired when home is triggeredcommunicate-triggerfullscreen-update- Fired when fullscreen is triggered- And more for each observable attribute
The component uses modern web standards (Custom Elements, Shadow DOM) and requires a modern browser with ES6+ support