Skip to main content
Photo Sphere Viewer uses angles extensively. You can express them as radians with a plain number (3.5) or in degrees with the deg suffix ('55deg').

​
Standard options

​
container
HTMLElement | string
required
HTML element which will contain the panorama, or an identifier string targeting the element.
// By element reference
container: document.querySelector('.viewer');

// By class name (targets [class="viewer"])
container: '.viewer';

// By id (targets [id="viewer"])
container: 'viewer';
​
panorama
*
required
Path to the panorama. Must be a single URL when using the default equirectangular adapter. Other adapters support different value shapes.
​
adapter
default:"equirectangular"
Which adapter is used to load the panorama.
​
plugins
array
List of enabled plugins. Each entry is either a plugin constructor or a tuple of [PluginConstructor, options].
​
caption
string
Text displayed in the navbar. HTML is allowed. Has no visible effect when the navbar is disabled.
​
description
string
Text displayed in the side panel when the user clicks the “i” button. HTML is allowed.
​
downloadUrl
string
default:"panorama (equirectangular)"
File that will be downloaded when the user clicks the download button. Particularly useful for adapters that use multiple files, such as the CubemapAdapter or EquirectangularTilesAdapter.
​
downloadName
string
default:"downloadUrl filename"
Overrides the filename used when downloading the panorama. Mainly useful when the panorama is provided as a base64 string.
​
size
{ width: integer, height: integer }
Final size of the panorama container. By default the size of container is used and followed when the element is resized.
​
navbar
Configuration of the navbar.
​
minFov
integer
default:"30"
Minimal field of view (maximum zoom level). Must be between 1 and maxFov.
​
maxFov
integer
default:"90"
Maximal field of view (minimum zoom level). Must be between minFov and 180.
​
defaultZoomLvl
integer
default:"50"
Initial zoom level, between 0 (for maxFov) and 100 (for minFov).
​
fisheye
boolean | double
default:"false"
Enables the fisheye effect. Pass true (equivalent to strength 1.0) or a numeric strength value.
Fisheye mode can have side-effects on marker rendering and some adapters.
​
defaultYaw
double | string
default:"0"
Initial horizontal angle, between 0 and 2π.
​
defaultPitch
double | string
default:"0"
Initial vertical angle, between -π/2 and π/2.
​
lang
object
Various text strings used throughout the viewer. Override any key to translate or customise the UI.
lang: {
  zoom: 'Zoom',
  zoomOut: 'Zoom out',
  zoomIn: 'Zoom in',
  moveUp: 'Move up',
  moveDown: 'Move down',
  moveLeft: 'Move left',
  moveRight: 'Move right',
  description: 'Description',
  download: 'Download',
  fullscreen: 'Fullscreen',
  loading: 'Loading...',
  menu: 'Menu',
  close: 'Close',
  twoFingers: 'Use two fingers to navigate',
  ctrlZoom: 'Use ctrl + scroll to zoom the image',
  loadError: 'The panorama cannot be loaded',
  webglError: 'Your browser does not seem to support WebGL',
}
​
loadingImg
string
Path to an image displayed in the centre of the loader.
​
loadingTxt
string
default:"lang.loading"
Text displayed in the centre of the loader. Only used when loadingImg is not set.
​
mousewheel
boolean
default:"true"
Enables zoom with the mouse wheel.
​
mousemove
boolean
default:"true"
Enables panorama rotation with click-and-drag or a finger swipe on touch screens.
​
keyboard
boolean | 'fullscreen' | 'always'
default:"'fullscreen'"
Enables keyboard controls. 'fullscreen' (same as true) activates controls only while in fullscreen mode. 'always' activates controls at all times.
When set to 'always', key events are listened globally on the page and can conflict with other interactive elements.
​
mousewheelCtrlKey
boolean
default:"false"
Requires holding Ctrl to zoom with the mouse wheel. This lets users scroll the page without accidentally zooming the viewer. When Ctrl is not held, an overlay prompt is shown.
​
touchmoveTwoFingers
boolean
default:"false"
Requires two fingers to rotate the panorama on touch screens, allowing standard single-finger page scrolling. When only one finger is detected, an overlay prompt is shown.

​
Advanced options

​
sphereCorrection
{ pan: double | string, tilt: double | string, roll: double | string }
default:"{ pan: 0, tilt: 0, roll: 0 }"
Corrects the panorama orientation. If the panorama file contains XMP pose data (heading/pitch/roll), those values are applied before sphereCorrection.
​
panoData
PanoData | function(image, xmpData) => PanoData
Overrides XMP data found in the panorama file. All sub-fields are optional.
panoData: {
  fullWidth: 6000,
  fullHeight: 3000,    // optional
  croppedWidth: 4000,  // optional
  croppedHeight: 2000, // optional
  croppedX: 1000,
  croppedY: 500,
}
​
defaultTransition
TransitionOptions
default:"{ speed: 1500, rotation: true, effect: 'fade' }"
Default transition used when switching between panoramas. All fields can be overridden per call to setPanorama().
  • effect: 'fade', 'black', or 'white'
  • speed: duration in milliseconds, or a string with revolutions per minute (e.g. '2rpm')
  • rotation: whether to animate camera rotation during the transition
​
moveSpeed
double
default:"1"
Speed multiplier for panorama movement (click-drag, touch swipe, and navbar move buttons).
​
zoomSpeed
double
default:"1"
Speed multiplier for panorama zoom (mouse wheel, touch pinch, and navbar zoom buttons).
​
moveInertia
boolean | number
default:"0.8"
Applies damping to camera movement. Higher values mean stronger damping. Pass false to disable, or true to use the default damping factor.
​
requestHeaders
object | function(url) => object
HTTP headers sent when loading image files.
requestHeaders: {
  header: 'value',
}
​
withCredentials
boolean | function(url) => boolean
default:"false"
Send credentials with HTTP requests.
// Dynamic example — skip credentials for certain hosts
withCredentials: (url) => !url.includes('amazonaws');
​
keyboardActions
object
Maps key codes to viewer actions. The key can include modifiers (Ctrl, Shift, Alt, Meta) separated by +.
// Defaults
keyboardActions: {
  'ArrowUp': 'ROTATE_UP',
  'ArrowDown': 'ROTATE_DOWN',
  'ArrowRight': 'ROTATE_RIGHT',
  'ArrowLeft': 'ROTATE_LEFT',
  'PageUp': 'ZOOM_IN',
  'PageDown': 'ZOOM_OUT',
  '+': 'ZOOM_IN',
  '-': 'ZOOM_OUT',
}
You can also assign an arbitrary callback. It receives the viewer instance and the original keyboard event.
import { DEFAULTS } from '@photo-sphere-viewer/core';

keyboardActions: {
  ...DEFAULTS.keyboardActions,
  'h': (viewer, evt) => {
    // do something when H is pressed
  },
  'Ctrl+1': (viewer) => {
    // do something when Ctrl + 1 is pressed
  },
}
Use Key.js to identify the exact key combination string for any keystroke. Use Plus instead of + when combining the plus key with a modifier, for example Shift+Plus.
Keyboard actions are only active in fullscreen by default. Change this with the keyboard option.
​
canvasBackground
string
default:"#000"
Background of the WebGL canvas, visible when using cropped panoramas. Accepts any valid CSS background value.
​
rendererParameters
WebGLRendererParameters
default:"{ alpha: true, antialias: true }"
Configuration passed directly to the Three.js WebGLRenderer. See the Three.js docs for available options.

​
Cache

Photo Sphere Viewer includes a global cache shared across all viewer instances. It saves resources when switching back and forth between multiple panoramas.
This cache is unrelated to the Three.js internal cache, which should remain disabled.
import { Cache } from '@photo-sphere-viewer/core';

Cache.enabled = false;
Cache.ttl = 300;
Cache.maxItems = 3;
​
Cache.enabled
boolean
default:"true"
Set to false to completely disable the cache.
​
Cache.ttl
number
default:"600"
Maximum retention duration in minutes.
​
Cache.maxItems
number
default:"10"
Maximum number of items stored. Note that cubemap and tile adapters store multiple files per panorama, so the actual file count may be higher.

Build docs developers (and LLMs) love

Get started for freeTalk to us