Streamlit IIIF viewer

A component for fast viewers integration inside Streamlit application.

IIIF (International Image Interoperability Framework) is a set of open standards for delivering high-quality images and metadata over the web. It is widely used in digital humanities and by cultural heritage institutions (but not only!) to share, annotate, and study digitized materials.

Currently, this component supports the following IIIF-compliant viewers:

• Mirador (Apache-2.0 License)
• Tify (GNU Affero General Public License v3.0)

Features

• Display IIIF v3 manifests
• port for document-focused viewer (e.g. Tify) and multi-window scholarly viewer (e.g. Mirador)
• Accepts either a remote manifest URL or a local JSON object
• Optional viewers configuration via options (language, theme, default window settings, etc.)
• Automatically resizes within the Streamlit layout
• Works seamlessly with Python dict IIIF manifests generated in the app

Installation

pip install streamlit-iiif-viewer

Quickstart

Display a remote manifest

import streamlit as st
from streamlit_iiif_viewer import iiif_viewer

st.title("My IIIF Viewer (remote)")

manifest_url = "https://iiif.io/api/cookbook/recipe/0009-book-1/manifest.json"

iiif_viewer(
    viewer="tify",  # or any IIIF viewers available like "mirador"
    manifest=manifest_url,
    height=800,
    options={"language": "fr"},  # optional viewer configuration
)

Display a local JSON manifest

import streamlit as st
from streamlit_iiif_viewer import iiif_viewer

st.title("My IIIF Viewer (local)")

manifest = {
    "@context": "http://iiif.io/api/presentation/3/context.json",
    "id": "https://example.org/manifest/demo",
    "type": "Manifest",
    "label": {"en": ["Local Demo"]},
    "items": [],
}

iiif_viewer(
    viewer="tify",  # or any IIIF viewers available like "mirador"
    manifest=manifest,
    height=700,
)

Viewer Configuration

You can customize the behavior of each viewer using the options argument. Full configuration guides are available in the official documentation:

• Mirador Configuration
• Tify Configuration

Important

For now, Mirador plugins like text-overlay or image-tools are not includes.

Tify Example

options = {
    "language": "de",
    "pageLabelFormat": "P (L)",
    "pages": [2, 3],
    "pan": {"x": ".45", "y": " .6"},
    "zoom": "1.2"
}

Mirador Example

options = {
"selectedTheme":"dark",
"language":"fr",
  "workspace": {
    "type": "mosaic"
  },
  "workspaceControlPanel": {
    "enabled": true
  },
  "theme": {
    "palette": {
      "type": "light"
    }
  }
}

Development

Note

These steps are required for development purposes or to modify the component code only.

1. Clone this repository:

git clone 
cd streamlit_iiif_viewer

2. Install the Python dependencies:

# create a virtual environment
python3.11 -m venv .venv
# activate it
. .venv/bin/activate
# install dependencies
pip3 install -r requirements.txt

3. Install frontend dependencies

cd streamlit_iiif_viewer/frontend
yarn install
npm install mirador # sometimes needed to explicitly install mirador (for build)

4. Making changes

To make changes, first go to streamlit_iiif_viewer/__init__.py and make sure the variable _RELEASE is set to False. This will make the component use the local version of the frontend code, and not the built project.

Then start the dev server for frontend:

cd streamlit_iiif_viewer/frontend/
yarn dev

this start VITE server at http://localhost:5173/.

Open another terminal and run the Streamlit app to test the component:

cd streamlit_iiif_viewer/
streamlit run __init__.py

References

Specific IIIF References

• IIIF Presentation API v3 – https://iiif.io/api/presentation/3.0/
• IIIF Cookbook (example manifests) – https://iiif.io/api/cookbook/

This template is based on these canvas/example projects:

• streamlit-component-vue-vite-template
• streamlit-drawable-canvas
• streamlit-calendar

and streamlit documentation:

• Streamlit Components – https://docs.streamlit.io/library/components