Introduction to plugins

Plugins are used to add new functionalities to Photo Sphere Viewer. They can access all internal APIs of the viewer as well as the Three.js renderer to make the viewer even more awesome.

Import official plugins

Official plugins (listed on the left menu) are available in various @photo-sphere-viewer/***-plugin packages. Some plugins also have an additional CSS file.

Example for the Markers plugin:

Using a plugin

All plugins consists of a JavaScript class which must be provided to the plugins array. Some plugins will also take a configuration object provided in a nested array.

const viewer = new Viewer({
    plugins: [
        PluginWithoutConfig,
        [PluginWithConfig, {
            option1: 'foo',
            option2: 'bar',
        }],
    ],
});

TIP

When using Typescript you can also type-check the configuration object :

import { MarkersPlugin, MarkersPluginConfig } from '@photo-sphere-viewer/markers-plugin';

const viewer = new Viewer({
    plugins: [
        [MarkersPlugin, {
            markers,
        } satisfies MarkersPluginConfig],
    ],
});

Methods and events

After initialization the plugin instance can be obtained with the getPlugin method, allowing to call methods on the plugin and subscribe to events.

const markersPlugin = viewer.getPlugin(MarkersPlugin);

markersPlugin.addMarker(/* ... */);

markersPlugin.addEventListener('select-marker', () => {
    /* ... */
});

Update options

Some plugins allow their configuration to be modified after init with the setOption() and setOptions() methods. The updatable configuration properties are documented on each plugin page.

markersPlugin.setOption('gotoMarkerSpeed', '3rpm');

markersPlugin.setOptions({
    gotoMarkerSpeed: '3rpm',
    clickEventOnMarker: true,
});