Mirador Documentation

Mirador uses a Redux-like pattern to manage state and perform operations. You interact with the viewer instance via actions to dispatch changes to the store.

Common tasks include:

• Adding a window: store.dispatch(actions.addWindow())
• Focusing a window: store.dispatch(actions.focusWindow('window-id'))
• Checking current state: store.getState()

// Add a window
store.dispatch(actions.addWindow());

// Focus a specific window
store.dispatch(actions.focusWindow('window-1'));

// Check current state
const state = store.getState();

To embed Mirador directly in an HTML document using the UMD build, include the script tag from unpkg.

Warning: Using @latest may cause breaking changes when Mirador transitions between major versions (e.g., v3 to v4). Pin your version in production.

Latest version:

<script src="https://unpkg.com/mirador@latest/dist/mirador.min.js"></script>

Pinned version (Recommended for production):

<script src="https://unpkg.com/mirador@^3/dist/mirador.min.js"></script>

You can install Mirador using a JavaScript package manager like npm or yarn. For advanced integrations involving plugins, it is recommended to use Vite with the ESM version of the packages.

If you want to embed Mirador in an HTML page without customization, use the UMD build via a CDN. For production environments, it is recommended to pin the version (e.g., to version 3) to avoid breaking changes when the latest tag updates.

$ npm install mirador 

# or

$ yarn add mirador

To develop Mirador locally, ensure Node.js is installed. Follow these steps:

1. Install dependencies: npm install
2. Start the project: npm start
3. Access the application at http://127.0.0.1:4444/

$ npm install
$ npm start

The AppProviders component includes a MaybeDndProvider that manages the drag-and-drop context. You can control this behavior using the dndManager prop:

1. Default Behavior: If dndManager is undefined, Mirador uses react-dnd-multi-backend with HTML5toTouch options, providing a robust experience across mouse and touch devices.
2. Custom Manager: If you pass a specific object to dndManager, Mirador will use that object as the value for the DndContext.Provider.
3. Disable Drag and Drop: If you pass false to dndManager, the drag-and-drop context is completely omitted from the component tree.

// To disable drag and drop
<AppProviders dndManager={false} ... />

// To use a custom manager
<AppProviders dndManager={myCustomDndManager} ... />

Mirador uses StoreAwareI18nextProvider to manage translations. You can inject additional translation bundles by passing a translations object to AppProviders.

The object should follow this structure:

{
  "language_code": { "translation": { "key": "value" } }
}

When the language prop changes, the provider automatically calls i18n.changeLanguage(). When the translations object is updated, it uses i18n.addResourceBundle to merge the new resources into the existing instance.

To enable a new language in the Mirador UI dropdown and allow for installation-level configuration, add the language code and its native name to the availableLanguages object in src/config/settings.js.

// src/config/settings.js
...
availableLanguages: {
    de: 'Deutsch',
    en: 'English',
    fr: 'Français',
    // Add your new language here
},

When an image fails to load, Mirador automatically displays a fallback placeholder. You can customize this by providing a fallbackImage URL in your configuration object.

Error messages can be customized by providing a translation for the imageFailedToLoad key. Detailed error information is logged to the console.

const config = {
  fallbackImage: 'https://example.com/custom-fallback.jpg',
};

To start using Mirador in your application, use the Mirador.viewer() method. You must provide an id which corresponds to the CSS selector of the element where Mirador should be instantiated.

The returned instance provides access to actions (for dispatching commands) and store (for managing state).

var miradorInstance = Mirador.viewer({
  id: 'mirador' // id selector where Mirador should be instantiated
});

// miradorInstance contains { actions, store }

Mirador is built using Vite to produce a Universal Module Definition (UMD) bundle. The build process targets ./src/index.js as the entry point and generates a minified file named mirador.min.js. The bundle is configured with exports: 'named' to ensure named exports are available in the UMD environment. Sourcemaps are enabled for debugging.

// The resulting UMD bundle will be available under the global name 'Mirador'
// and the file will be named 'mirador.min.js'

Mirador uses Vitest for testing and includes linting/size checks.

• Run all tests: npm test
• Run tests with Vitest UI: npm test -- --ui
• Run a specific test file with UI: npx vitest <path-to-file> --ui
• Run linting: npm run lint
• Debug tests: npm run test:debug

# Run tests
$ npm test

# Run tests with UI
$ npm test -- --ui

# Run linting
$ npm run lint

# Debug tests
$ npm run test:debug