Skip to main content
The Gallery plugin displays a horizontal strip of thumbnails at the bottom of the viewer. Users can switch between panoramas by clicking a thumbnail. It integrates naturally with the Virtual Tour plugin.
GalleryPlugin is not compatible with ResolutionPlugin.

Installation

npm install @photo-sphere-viewer/gallery-plugin
This plugin requires its stylesheet. Import @photo-sphere-viewer/gallery-plugin/index.css or add the CDN link to your <head>.

Usage

import { Viewer } from '@photo-sphere-viewer/core';
import { GalleryPlugin } from '@photo-sphere-viewer/gallery-plugin';

const viewer = new Viewer({
    plugins: [
        GalleryPlugin.withConfig({
            items: [
                {
                    id: 'pano-1',
                    name: 'Panorama 1',
                    panorama: 'path/to/pano-1.jpg',
                    thumbnail: 'path/to/pano-1-thumb.jpg',
                },
                {
                    id: 'pano-2',
                    name: 'Panorama 2',
                    panorama: 'path/to/pano-2.jpg',
                    thumbnail: 'path/to/pano-2-thumb.jpg',
                },
            ],
        }),
    ],
});

Configuration

items
GalleryItem[]
The list of panorama items. Not updatable after init — use setItems() instead.
visibleOnLoad
boolean
default:"false"
Show the gallery when the first panorama loads. The user can toggle it with the navbar button.
hideOnClick
boolean
default:"true"
Close the gallery when the user selects an item. Always true on screens narrower than 500px. Updatable.
navigationArrows
boolean
default:"false"
Show left/right navigation arrows on the sides of the gallery.
thumbnailSize
{ width: number, height: number }
default:"{ width: 200, height: 100 }"
Size of each thumbnail in pixels. Updatable.
lang
object
Localization strings merged with the main viewer lang object.
lang: {
    gallery: 'Gallery',
}

Item options

id
number | string
required
Unique identifier for the item.
panorama
required
The panorama to display. Accepts the same value as the main viewer panorama option.
thumbnail
string
default:"''"
URL of the thumbnail image shown in the gallery strip.
name
string
default:"''"
Text label shown over the thumbnail.
options
PanoramaOptions
default:"null"
Any options supported by the setPanorama() method, applied when this item is selected.

Methods

setItems(items)

Replaces the current gallery items. This plugin adds a gallery button to the default navbar to toggle the gallery panel.
If you use a custom navbar, add 'gallery' to your navbar configuration manually.

SCSS variables

VariableDefaultDescription
$breakpoint500pxScreen width below which the gallery is displayed full-height
$padding15pxContainer padding
$border1px solid core.$buttons-colorBorder between gallery and navbar
$backgroundcore.$navbar-backgroundGallery background
$item-radius5pxCorner radius of gallery items
$item-active-border3px solid whiteBorder of the active gallery item
$title-fontcore.$caption-fontFont of the item title
$title-colorcore.$caption-text-colorColor of the item title
$title-backgroundrgba(0, 0, 0, .6)Background behind the item title
$thumb-hover-scale1.2Scale factor of thumbnails on hover
$arrow-colorrgba(255, 255, 255, 0.6)Color of navigation arrows
$arrow-backgroundrgba(0, 0, 0, 0.6)Gradient behind navigation arrows
$scrollbar-color$arrow-colorScrollbar color (browser support required)

Build docs developers (and LLMs) love