Skip to main content
Plugins extend Photo Sphere Viewer with new features. They can access all internal viewer APIs and the Three.js renderer. Official plugins are published as separate npm packages under the @photo-sphere-viewer/ scope.

​
Available plugins

Markers

Display images, HTML, SVG shapes, polygons, and polylines on the panorama with optional tooltips and click events.

Virtual tour

Link multiple panoramas together into an explorable virtual tour with navigation arrows and GPS support.

Gallery

Show a thumbnail gallery at the bottom of the viewer so users can navigate between panoramas.

Map

Display a custom image map overlay showing the viewer’s current position and optional hotspots.

Plan

Show a geographic map (OpenStreetMap or custom tile layer) with the panorama’s GPS position.

Autorotate

Automatically rotate the panorama after a period of inactivity.

Compass

Show a compass overlay indicating the current viewing direction.

Gyroscope

Use device gyroscope data to control the viewing direction on mobile devices.

Stereo

Display the panorama in stereoscopic VR mode for use with headsets.

Video

Control playback of video panoramas loaded with the equirectangular-video or cubemap-video adapters.

Overlays

Add static or video overlay images on top of the panorama.

Resolution

Allow users to switch between multiple resolutions of the same panorama.

Settings

Add a configurable settings panel to the viewer toolbar.

Visible range

Restrict the yaw, pitch, and zoom ranges the user can navigate to.

​
Installation

Each plugin is a separate package. Install the one you need: 
npm install @photo-sphere-viewer/markers-plugin
Some plugins also require a CSS file. Import it alongside the JavaScript module. 
<head>
    <!-- stylesheet for the plugin -->
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@photo-sphere-viewer/markers-plugin/index.min.css" />
</head>

<script type="importmap">
    {
        "imports": {
            "@photo-sphere-viewer/core": "https://cdn.jsdelivr.net/npm/@photo-sphere-viewer/core/index.module.js",
            "three": "https://cdn.jsdelivr.net/npm/three/build/three.module.js",
            "@photo-sphere-viewer/markers-plugin": "https://cdn.jsdelivr.net/npm/@photo-sphere-viewer/markers-plugin/index.module.js"
        }
    }
</script>

<script type="module">
    import { Viewer } from '@photo-sphere-viewer/core';
    import { MarkersPlugin } from '@photo-sphere-viewer/markers-plugin';

    const viewer = new Viewer({
        plugins: [
            MarkersPlugin,
        ],
    });
</script>

​
Using a plugin

Pass the plugin class to the plugins array when creating the Viewer. Plugins that accept configuration use the static withConfig method: 
const viewer = new Viewer({
    plugins: [
        PluginA,
        PluginB.withConfig({
            option1: 'foo',
            option2: 'bar',
        }),
    ],
});

​
Accessing the plugin instance

After initialization, retrieve the plugin instance with getPlugin to call methods and subscribe to events: 
const markersPlugin = viewer.getPlugin(MarkersPlugin);

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

markersPlugin.addEventListener('select-marker', ({ marker }) => {
    console.log(`Clicked marker: ${marker.id}`);
});

​
Updating options at runtime

Some plugins support updating their configuration after initialization using setOption or setOptions. Each plugin’s documentation notes which options are updatable: 
markersPlugin.setOption('gotoMarkerSpeed', '3rpm');

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

Build docs developers (and LLMs) love

Get started for freeTalk to us