Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »


2.1.0 • Public • Published


Image of OpenSeadragon React Viewer

A React wrapper component around the OpenSeadragon viewer. Feed OpenSeadragonViewer a IIIF manifest URL, and it will render an OpenSeadragon viewer with:

  • FontAwesome toolbar icons
  • A tile source dropdown navigation menu
  • Thumbnails navigation
  • Download options
  • Support for deep linking, and saving URL parameters

Installation and usage

yarn add openseadragon-react-viewer

// And peer dependencies
yarn add @emotion/core openseadragon

Then use it in your app:

import React from 'react';
import { OpenSeadragonViewer } from "openseadragon-react-viewer"

const App = () => {
  // Get your manifest from somewhere
  const manifestUrl = "https://some-manifest-url-here.json";

  // Options to show/hide extra UI features in the viewer
  // height(in pixels) option is default to 800 for wide-screens and 500 for narrow-screens
  // All other options default to 'true'
  const options = {
    showDropdown: true,
    showThumbnails: false,
    showToolbar: true,
    deepLinking: true,
    height: 800,

  return (
    <OpenSeadragonViewer manifestUrl={manifestUrl} options={options} />

export default App;

Options / Props

Props the component accepts:

  • manifestUrl - {string} IIIF manifest url (required)
  • options - {object} An options config object whether to use custom features or OpenSeadragon features

See the Styleguidist docs for full configuration options.

Custom styling

CSS class names are provided for elements which allow for custom styling overrides.

For example, to change the style of the title in the viewer, in your CSS define something like:

.osrv-work-title {
  color: green;
  font-family: "Verdana";
  font-size: 2rem;



You'll need to have node installed on your local machine. Also, preferably yarn installed as well. You can check either with:

node --version
yarn --version


  1. Clone or fork this repository

  2. Install project dependencies

yarn install

Start development environment

To spin up the development environment run:

yarn dev

Visit http://localhost:10001/ in your browser.

See rollup.config.js for development and packaging configuration details. Development environment runs from a UMD bundled file, which is saved to the /public folder for local development.

Running the tests

To run unit tests, with a full coverage report:

yarn test

To run tests in watch mode:

yarn test:watch

Styleguidist development

Styleguidist, in addition to providing documentation, also offers an isolated development environment. To run the environment and test it out:

yarn styleguide

To build a static html version of the docs (which Github pages uses), run:

yarn styleguide:build


To deploy your forked version of this repo, run:

yarn build

This will create CommoneJS, ES Module, and UMD distribution files located in the /dist/ directory.


See the Styleguidist docs for documentation on the components.


If you're working on PR for this project, branch off master and create a feature branch. Submit your PR to https://github.com/samvera-labs/openseadragon-react-viewer. You're awesome. Thanks!

Code style

Use Prettier.

.prettierrc file contains current project coding style settings.

Built With

  • OpenSeadragon - OpenSeadragon
  • IIIF - IIIF International Image Interoperability Framework
  • React - JavaScript component library
  • Rollup - JavaScript Bundler
  • Jest - Testing framework
  • Emotion - CSS in JS


We use SemVer for versioning. For the versions available, see the tags on this repository.



This project is licensed under the MIT License - see the LICENSE.md file for details




npm i openseadragon-react-viewer

DownloadsWeekly Downloads






Unpacked Size

436 kB

Total Files


Last publish


  • avatar
  • avatar