OpenSeadragon API

Getting Started

OpenSeadragon has no external dependencies. To install, download and copy the openseadragon folder into your web root or static files directory, add it to your page, and create a viewer with new OpenSeadragon.Viewer(options) or OpenSeadragon(options) for short.

Here is an example of basic usage:

<div id="openseadragon1" style="width: 800px; height: 600px;"></div>
<script src="/openseadragon/openseadragon.min.js"></script>
<script type="text/javascript">
    var viewer = OpenSeadragon({
        id: "openseadragon1",
        prefixUrl: "/openseadragon/images/",
        tileSources: "/path/to/my/image.dzi"
    });
</script>

Important: The container you give OpenSeadragon needs to have its own width and height (like in the example above) or you won't see anything!

OpenSeadragon will also return an AMD or CommonJs module when required with a loader like Require.js, Webpack or Browserify.

You will, of course, need zooming image data to work with. See Creating Zooming Images.

For more information on the options object you pass in to OpenSeadragon(), see OpenSeadragon.Options. To learn more about the viewer that it creates, see OpenSeadragon.Viewer. For programmatic control of zoom and pan, see OpenSeadragon.Viewport.

For other advanced topics, see our Examples & Features pages. More useful info can be found in our FAQ.

If you are working directly from the file system (accessing your web page from file:///path/to/your/file.htm) you may need to change your browser's local files security policy so that your zooming image data can be loaded. Alternatively, you can run a local server. You can find help on both methods in three.js documentation.

Important note for Angular users

By default Angular enables change detection in all imported code, which introduces a lot of CPU load in UI intensive libraries. To avoid this, you must create Openseadragon object out of NgZone. Instead of

const viewer = OpenSeadragon(options);

use

const viewer = this.ngZone.runOutsideAngular(() =>
  OpenSeadragon(options)
);