iiif-browser
v2.3.2
Published
The IIIF Browser (v2) is a powerful and flexible web application for browsing and interacting with IIIF content. This documentation will guide you through the various configuration options available to customize the IIIF Browser to suit your needs.
Readme
IIIF Browser
The IIIF Browser (v2) is a powerful and flexible web application for browsing and interacting with IIIF content. This documentation will guide you through the various configuration options available to customize the IIIF Browser to suit your needs.
Configuration Options
IIIFBrowserConfig
The IIIFBrowserConfig interface defines the configuration options for the
IIIF Browser's user interface (UI).
export interface IIIFBrowserConfig {
defaultPages: {
homepage: boolean;
about: boolean;
history: boolean;
bookmarks: boolean;
viewSource: boolean;
};
backButton: boolean;
forwardButton: boolean;
reloadButton: boolean;
homeButton: boolean;
bookmarkButton: boolean;
menuButton: boolean;
manifestInfoButton?: boolean;
/** @deprecated Use manifestInfoButton instead. */
showManifestMetadata: boolean;
collectionPaginationSize: number;
manifestPaginationSize: number;
paginationNavigationType: "replace" | "push";
portalIcons: boolean;
homeLink: string;
}Options
- defaultPages: Configuration for default pages.
homepage: Enable or disable the homepage.about: Enable or disable the about page.history: Enable or disable the history page.bookmarks: Enable or disable the bookmarks page.viewSource: Enable or disable the view source page.
- backButton: Show or hide the back button.
- forwardButton: Show or hide the forward button.
- reloadButton: Show or hide the reload button.
- homeButton: Show or hide the home button.
- bookmarkButton: Show or hide the bookmark button.
- menuButton: Show or hide the menu button.
- manifestInfoButton: Show or hide manifest information in the URL bar.
- showManifestMetadata: Deprecated alias for
manifestInfoButton. - collectionPaginationSize: Number of items per page in collections.
- manifestPaginationSize: Number of items per page in manifests.
- paginationNavigationType: Type of navigation for pagination (
replaceorpush). - portalIcons: Enable or disable portal icons.
- homeLink: URL for the home button.
BrowserLinkConfig
The BrowserLinkConfig interface defines the configuration options for link
behavior within the IIIF Browser.
export type BrowserLinkConfig = {
allowNavigationToBuiltInPages: boolean;
onlyAllowedDomains: boolean;
canSelectOnlyAllowedDomains: boolean;
allowedDomains: string[];
disallowedResources: string[];
markedResources: string[];
multiSelect: boolean;
alwaysShowNavigationArrow: boolean;
clickToSelect: boolean;
doubleClickToNavigate: boolean;
clickToNavigate: boolean;
canNavigateToCollection: boolean;
canNavigateToManifest: boolean;
canNavigateToCanvas: boolean;
canSelectCollection: boolean;
canSelectManifest: boolean;
canSelectCanvas: boolean;
customCanNavigate: null | ((resource: any, vault: Vault) => boolean);
customCanSelect: null | ((resource: any, vault: Vault) => boolean);
};Options
- allowNavigationToBuiltInPages: Allow navigation to built-in pages.
- onlyAllowedDomains: Restrict navigation to allowed domains.
- canSelectOnlyAllowedDomains: Restrict selection to allowed domains.
- allowedDomains: List of allowed domains for navigation and selection.
- disallowedResources: List of disallowed resources.
- markedResources: List of marked resources (not yet implemented)
- multiSelect: Enable or disable multi-selection.
- alwaysShowNavigationArrow: Always show the navigation arrow.
- clickToSelect: Enable or disable click to select.
- doubleClickToNavigate: Enable or disable double-click to navigate.
- clickToNavigate: Enable or disable click to navigate.
- canNavigateToCollection: Allow navigation to collections.
- canNavigateToManifest: Allow navigation to manifests.
- canNavigateToCanvas: Allow navigation to canvases.
- canSelectCollection: Allow selection of collections.
- canSelectManifest: Allow selection of manifests.
- canSelectCanvas: Allow selection of canvases.
- customCanNavigate: Custom function to determine if navigation is allowed.
- customCanSelect: Custom function to determine if selection is allowed.
BrowserStoreConfig
The BrowserStoreConfig interface defines the configuration options for the
browser store.
export type BrowserStoreConfig = {
requestInitOptions?: RequestInit;
initialHistory: Array<HistoryItem>;
initialHistoryCursor: number;
historyLimit: number;
restoreFromLocalStorage: boolean;
saveToLocalStorage: boolean;
localStorageKey: string;
preprocessManifest?: (manifest: Manifest) => Promise<Manifest>;
preprocessCollection?: (collection: Collection) => Promise<Collection>;
collectionUrlMapping: Record<string, string>;
collectionUrlMappingParams: Record<string, string>;
seedCollections: Array<Collection>;
};Options
- requestInitOptions: Options for fetch requests.
- initialHistory: Initial history items.
- initialHistoryCursor: Initial history cursor position.
- historyLimit: Maximum number of history items.
- restoreFromLocalStorage: Restore history from local storage.
- saveToLocalStorage: Save history to local storage.
- localStorageKey: Key for local storage.
- preprocessManifest: Function to preprocess manifests.
- preprocessCollection: Function to preprocess collections.
- collectionUrlMapping: Mapping of collection URLs.
- collectionUrlMappingParams: Parameters for collection URL mapping.
- seedCollections: Seed collections to load initially.
OutputTarget
The OutputTarget interface defines the configuration options for output
targets.
export type OutputTarget = {
label: string;
format: OutputFormat;
supportedTypes: OutputType[];
inlineAction?: boolean;
} & OutputTargetTypes;Options
- label: Label for the output target.
- format: Format of the output (e.g., URL, JSON).
- supportedTypes: Supported types for the output (e.g., Manifest, Collection).
- inlineAction: Whether the action is inline.
Example Usage
Here is an example of how to configure and use the IIIF Browser:
import { IIIFBrowser } from "iiif-browser";
export default function App() {
return (
<IIIFBrowser
ui={{
defaultPages: {
homepage: true,
about: true,
history: true,
bookmarks: false,
viewSource: true,
},
backButton: true,
forwardButton: true,
reloadButton: true,
homeButton: true,
bookmarkButton: false,
menuButton: true,
manifestInfoButton: true,
collectionPaginationSize: 25,
manifestPaginationSize: 25,
paginationNavigationType: "replace",
portalIcons: true,
homeLink: "iiif://home",
}}
history={{
localStorageKey: "iiif-browser-history",
restoreFromLocalStorage: true,
saveToLocalStorage: true,
initialHistory: [
{
url: "iiif://home",
resource: null,
route: "/",
},
],
initialHistoryCursor: 0,
historyLimit: 100,
}}
navigation={{
allowNavigationToBuiltInPages: true,
onlyAllowedDomains: false,
canSelectOnlyAllowedDomains: false,
allowedDomains: [],
disallowedResources: [],
markedResources: [],
multiSelect: true,
alwaysShowNavigationArrow: true,
clickToSelect: true,
doubleClickToNavigate: false,
clickToNavigate: true,
canNavigateToCollection: true,
canNavigateToManifest: true,
canNavigateToCanvas: true,
canSelectCollection: true,
canSelectManifest: true,
canSelectCanvas: true,
}}
output={[
{
label: "Open in Viewer",
type: "open-new-window",
urlPattern: "https://example.org/viewer?manifest={MANIFEST}",
format: { type: "url", resolvable: true },
supportedTypes: ["Manifest"],
},
]}
/>
);
}This example demonstrates how to configure the IIIF Browser with custom UI options, history settings, navigation behavior, and output targets. Adjust the configuration options to suit your specific requirements.
Theming: dark mode and accent colour
The browser has a light theme (default) and a dark theme that uses the Theseus palette: surfaces keep a slight blue tint rather than going full black. Both the accent colour and the theme can be set from props.
<IIIFBrowser
theme="dark" // "light" | "dark" | "system" (follows prefers-color-scheme)
accentColor="#0d9488" // hex, rgb(13 148 136) or "13 148 136"
/>- Menu toggle – when
themeis not set, the 3-line menu has a Dark mode / Light mode item. The choice is remembered inlocalStorage(shared between browsers, or scoped withpreferenceKey). Hide it withui={{ themeToggle: false }}. - Host controlled – setting
thememakes the host the owner and hides the menu toggle. AddonThemeChangeto keep the toggle and receive the viewer's choice. - Accent colour – applies to buttons, links, selection and focus rings. The button label colour (white or black) is picked automatically so it has at least 4.5:1 contrast on the fill, the fill keeps 3:1 against the surface, and accent text is lightened/darkened to stay readable on the surface in each theme. The default accent is Tailwind blue-600 (
#2563eb). - Notebook –
<IIIFNotebook theme="dark" accentColor="#e0457b" />. A notebook rendered inside anIIIFBrowser(e.g. vianotebookPlugin), or a browser opened inside a notebook dialog, follows the surrounding theme. If you renderNotebookResourceBrowseror the editor dialogs yourself, wrap them inThemeProvider(exported fromiiif-browserandiiif-browser/notebook).
Theming is implemented with --ib-* CSS variables (space separated channels, e.g. --ib-gray-500) that the stylesheet reads with Tailwind's colours as the fallback, so the default light theme adds no inline styles. Custom components can use the bg-accent, hover:bg-accent-hover and text-accent-text Tailwind classes for filled accent surfaces. See the Theming stories in Storybook.
MDXEditor plugin
@mdxeditor/editor is an optional peer dependency. Install it in the app that
uses the integration, then add the plugin and toolbar button:
import {
MDXEditor,
toolbarPlugin,
} from "@mdxeditor/editor";
import "@mdxeditor/editor/style.css";
import "iiif-browser/mdx-plugins.css";
import {
iiifBrowserPlugin,
InsertIIIFBrowser,
} from "iiif-browser/mdxeditor";
<MDXEditor
markdown="Choose an image"
plugins={[
iiifBrowserPlugin({
image: { width: 1200 },
canvasSnippet: true,
browserProps: {
ui: { buttonClassName: "my-iiif-action" },
navigation: { canSelectManifest: false },
},
}),
toolbarPlugin({
toolbarContents: () => <InsertIIIFBrowser />,
}),
]}
/>The default action inserts an Image API <img />. Width, height, rotation,
crop, format, and quality can be configured; canvasSnippet adds a Markdown
image and caption action. Pass normal IIIFBrowser options through
browserProps, and modal classes, styles, title, and labels through dialog.
The toolbar defaults to the image-stack icon; set icon: "add" on
iiifBrowserPlugin to use the IIIF add mark instead.
Selection uses two screens: choose or crop an image in the browser, then
confirm the request using the service's info.json sizes, limits, formats,
qualities, and rotation support. Selecting an existing IIIF image in MDXEditor
and opening its image settings uses the same options screen, including a
“Remove crop” action.
When an MDXEditor image is resized, non-preset Image API URLs are updated to
match the rendered width at twice the pixel density. Configure this using
image.resizeMultiplier (for example 1, 1.5, or 2), or set it to false
to leave the URL unchanged.
Manifest and Collection snippets
The separate snippet plugin inserts configurable MDX components for IIIF Collections, Manifests, and Canvases:
import { MDXEditor, toolbarPlugin } from "@mdxeditor/editor";
import {
InsertIIIFSnippet,
iiifSnippetPlugin,
} from "iiif-browser/mdxeditor-snippet";
<MDXEditor
markdown="Choose a IIIF resource"
plugins={[
iiifSnippetPlugin({
defaultSize: { width: 640, height: 420 },
browserProps: {
navigation: { canSelectCanvas: true },
},
}),
toolbarPlugin({
toolbarContents: () => <InsertIIIFSnippet />,
}),
]}
/>Choose a resource in the IIIF Browser to insert it immediately. Inserted default
snippets include IIIFSnippetProvider and can be resized directly in MDXEditor;
the final width and height are written back to the MDX when the pointer is
released. The toolbar defaults to the IIIF add mark; set icon: "stack" on
iiifSnippetPlugin to use the image-stack icon instead.
Collection snippets start with a responsive grid of square Manifest thumbnails
and two-line labels. Choosing an item opens its deep-zoom viewer in place, with
a bottom breadcrumb to return to the collection. Set
collectionNavigation: "button" to insert an over-image Collection button
instead.
Use components to change the component name, import source, default props, or
editor preview for each resource type. Set provider: false for components
that load their own resources, or defaultSize: false to omit dimensions.
Normal IIIF Browser options are passed through browserProps; titles, classes,
and styles can be customized through dialog.
Optional TipTap integration
See TIPTAP.md for Image API images, interactive IIIF snippets, and IIIF Content State drag-and-drop support in TipTap and MDXEditor. Preview the integrations in Storybook under Integrations.
Project notebooks
The optional iiif-browser/notebook plugin adds an embeddable
Tiptap notebook with smart IIIF links, resource previews, interactive checklists,
project context, and shared browser search/save integration. See
Integrations / Notebook / Manifest Editor in Storybook for a working host app.
Selection, rotation and image URLs
By default, resource clicks navigate until the first explicit checkbox or drag
selection. With an active manual selection, clicks on selectable resources select
instead. Set navigation.clickToSelect to true for immediate click selection,
false for navigation-only clicks, or "after-selection" (the default). Clearing
the manual selection restores ordinary browsing. Ctrl/Cmd/Shift clicks toggle
items when multiSelect is enabled.
With clickToNavigate: false, navigation arrows remain available in both grid and
list views. Non-selectable collections and manifests still open on a click, and
doubleClickToNavigate can also be enabled. Resource/domain navigation
restrictions continue to apply.
The viewer uses Atlas's viewRotation camera API. Crops remain in the original
Canvas coordinate system; returned selection state includes rotation separately.
Content State output includes the crop fragment and an ImageApiSelector for
rotation. Canvas routes retain xywh, rotation, and the selected image choice.
To return a rendered IIIF image request, use this output target:
{
type: "callback",
label: "Select image",
supportedTypes: ["Canvas", "CanvasRegion"],
format: { type: "image-url", width: 600 },
cb: (url) => console.log(url),
}The URL uses the chosen painting's Image API service and includes its image-space
crop and rotation. Small crops are limited to their source dimensions to avoid
implicit upscaling. image-service continues to return the service identifier or
information document, rather than rendered pixels. The image server must support
the requested crop, size and rotation.
See IIIF Browser / Regression in Storybook and REGRESSION_TESTING.md for the test matrix and repeatable browser workflow.
The output action selected from More actions becomes the primary action and
is remembered in local storage. Preferences are scoped to the browser's
configuration and complete output list; an unavailable preferred action falls
back to the first available action without discarding the preference. Use a
stable, distinct preferenceKey on each IIIFBrowser when multiple instances
have otherwise identical configurations, for example preferenceKey="notebook-image-picker".
