Skip to main content
The Settings plugin adds a Settings button to the navbar and a settings panel that other plugins can populate. On its own it does nothing — it is a dependency for plugins such as Resolution.

​
Installation

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

​
Usage

import { Viewer } from '@photo-sphere-viewer/core';
import { SettingsPlugin } from '@photo-sphere-viewer/settings-plugin';

const viewer = new Viewer({
    panorama: 'path/to/panorama.jpg',
    plugins: [
        SettingsPlugin,
    ],
});

const settingsPlugin = viewer.getPlugin(SettingsPlugin);

​
Adding a setting

Call addSetting() on the plugin instance. There are two setting types.

​
Toggle setting

A toggle has only two states: true and false. Provide active() and toggle() callbacks. 
let enabled = false;

settingsPlugin.addSetting({
    id: 'custom-toggle-setting',
    label: 'Toggle setting',
    type: 'toggle',
    active: () => enabled,
    toggle: () => (enabled = !enabled),
});

​
Options setting

An options setting has multiple values. Provide current(), options(), and apply() callbacks. 
let currentOption = 'A';

settingsPlugin.addSetting({
    id: 'custom-options-setting',
    label: 'Options setting',
    type: 'options',
    options: () => [
        { id: 'A', label: 'Option A' },
        { id: 'B', label: 'Option B' },
    ],
    current: () => currentOption,
    apply: (option) => (currentOption = option),
});
Both label values accept a key from the main viewer lang object for translation purposes.

​
Button badge

A setting can expose a badge function whose return value is shown as a badge on the settings button itself. Only one setting can declare a badge at a time. 
settingsPlugin.addSetting({
    // ...
    badge: () => currentOption,
});

​
Configuration

​
persist
boolean
default:"false"
Persist setting values across sessions using the configured storage. Not updatable after init.
​
storage
object
default:"LocalStorage (key: psvSettings)"
Custom storage backend for persisting settings. Provide get and set methods. Not updatable after init.
{
    get(settingId: string): boolean | string | Promise<boolean | string>;
    set(settingId: string, value: boolean | string): void;
}
Compatible with LocalForage, NgRx, a custom HTTP service, or any async key-value store.
​
lang
object
Localization strings merged with the main viewer lang object.
lang: {
    settings: 'Settings',
}

​
Events

​
setting-changed

Triggered when a setting value changes. 
settingsPlugin.addEventListener('setting-changed', ({ settingId, settingValue }) => {
    console.log(`${settingId}: ${settingValue}`);
});
This plugin adds one button to the default navbar:
  • settings — opens the settings panel
If you use a custom navbar, add 'settings' to your navbar configuration manually.

​
SCSS variables

VariableDefaultDescription
$fontcore.$caption-fontFont used in the settings panel
$text-colorcore.$panel-text-colorText color
$backgroundcore.$panel-backgroundPanel background color
$item-heightcore.$panel-menu-item-heightHeight of each settings item
$item-paddingcore.$panel-menu-item-paddingPadding of each settings item
$hover-backgroundcore.$panel-menu-hover-backgroundItem background on hover
$badge-font10px / .9 monospaceFont of the button badge
$badge-text-colorwhiteText color of the badge
$badge-background#111Background color of the badge

Build docs developers (and LLMs) love

Get started for freeTalk to us