npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

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 (replace or push).
  • 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 theme is not set, the 3-line menu has a Dark mode / Light mode item. The choice is remembered in localStorage (shared between browsers, or scoped with preferenceKey). Hide it with ui={{ themeToggle: false }}.
  • Host controlled – setting theme makes the host the owner and hides the menu toggle. Add onThemeChange to 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 an IIIFBrowser (e.g. via notebookPlugin), or a browser opened inside a notebook dialog, follows the surrounding theme. If you render NotebookResourceBrowser or the editor dialogs yourself, wrap them in ThemeProvider (exported from iiif-browser and iiif-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".