Skip to content


Repository files navigation


plugin for openseadragon image viewer. this plugin adds the ability to select regions of the image by mouse gestures.


$   npm i openseadragon-select-plugin


Include openseadragon-select-plugin after OpenSeadragon in your file.

    import { Viewer } from 'openseadragon';
    import 'openseadragon-select-plugin'

    const viewer = new Viewer({})

Then after you create a viewer you can call the selection method from the viewer instance:

    const selection = viewer.selection(options);


the options is just an object with a callback function who is called once the selecting is done:

    interface ViewerSelectionOptions {
	 * callback that will be called after the drawing is done.
	 * @param rect bounding box of the selected aria
	 * @param shape the shape object used to draw the selection
	 * @required
	onSelection: (rect: Rect, shape: BaseShape) => void;
	 * if set to true, the shape will automatically
	 * be added to the canvas after drawing is finished.
	 * @default false
	keep: boolean;


the selection object has two methods:

    * activate drawing mode
    * deactivate drawing mode

you can also add shapes to be displayed on the image by calling:


and remove them by:


    // or remove all by:

note: if you want to add shapes without using the viewer.selection function, you need to initialize it first by calling initSelection:



you can customize the drawing process by changing the drawOptions, or evan add custom shapes to be drawn while selecting instead of default rectangle.


you can change the drawing options, be setting:

    viewer.selectionHandler.drawer.drawOptions = {...newOptions}

defaults to:

    const defaultDrawingOptions = {
        color: 'rgb(200, 0, 0)',
        lineWidth: 2,
        fill: 'rgba(220,220,220,0.2)',


the default shape is RectShape but PolygonShape, BrushShape LineShape and PointShape are also available.

other shapes can be activated by:


you can add custom shapes by extending the abstract BaseShape class

    import { BaseShape } from 'openseadragon-select-plugin';

    class CustomShape extends BaseShape {

or even create complex shapes by extending the abstract GroupShape class:

    class PolygonShape extends GroupShape<
        LineShape | PointShape
    > {
        get shapes (): BaseShape[] {
            return [];

you will need to implement these abstract methods/fields:

    class CustomShape extends BaseShape {
        readonly boundingBox: Rect;

        * this is not required in `GroupShape`
        toPath2D(): Path2D;

        startDrawing(point: Point): void;
        updateDrawing(point: Point): void;
        endDrawing(point?: Point): void;

once drawing is finished you need to call this.finishDrawing().

registering a custom shape:

custom shapes need to be registered manually:

    viewer.selectionHandler.drawer.addShapes(, customShapesConstructor)

and then you can select them by:



Apache 2.0