Photo Sphere Viewer includes a markers system since version 3.1. It allows to define points of interest on the Photo Sphere with optional tooltip and description. It also allows to dynamically add and remove markers on user click/tap.

There are four types of markers :

  • HTML defined with the html attribute
  • Images defined with the image attribute
  • SVGs defined with the rect, circle, ellipse or path attribute
  • Dynamic polygons & polylines defined with the polygon_px/polygon_rad/polyline_px/polyline_rad attribute


The following example contains all types of markers. Click anywhere on the panorama to add a red marker, click again to remove it.

 * Initialize the viewer
var PSV = new PhotoSphereViewer({
  // main configuration
  panorama: rootURL + '/assets/Bryce-Canyon-National-Park-Mark-Doliner.jpg',
  container: 'photosphere',
  loading_img: rootURL + '/assets/photosphere-logo.gif',
  time_anim: false,
  caption: 'Bryce Canyon National Park <b>&copy; Mark Doliner</b>',
  default_fov: 70,
  default_lat: 0.3,
  mousewheel: false,
  touchmove_two_fingers: true,
  size: {
    height: 500

  // list of markers
  markers: [
      // image marker that opens the panel when clicked
      id: 'image',
      longitude: 0.2,
      latitude: -0.13770,
      image: rootURL + '/assets/pin-blue.png',
      width: 32,
      height: 32,
      anchor: 'bottom center',
      tooltip: 'A image marker. <b>Click me!</b>',
      content: document.getElementById('lorem-content').innerHTML
      // html marker with custom style
      id: 'text',
      longitude: 0,
      latitude: 0,
      html: 'HTML <b>marker</b> &hearts;',
      anchor: 'bottom right',
      scale: [0.5, 1.5],
      style: {
        maxWidth: '100px',
        color: 'white',
        fontSize: '20px',
        fontFamily: 'Helvetica, sans-serif',
        textAlign: 'center'
      tooltip: {
        content: 'An HTML marker',
        position: 'right'
      // polygon marker
      id: 'polygon',
      polygon_px: [
        [3184, 794], [3268, 841], [3367, 1194],
        [3327, 1307], [3065, 1221], [3097, 847]
      svgStyle: {
        fill: 'rgba(200, 0, 0, 0.2)',
        stroke: 'rgba(200, 0, 50, 0.8)',
        strokeWidth: '2px'
      tooltip: {
        content: 'A dynamic polygon marker',
        position: 'right bottom'
      // polyline marker
      id: 'polyline',
      polyline_rad: [
        [5.924, 0.064], [5.859, -0.061], [5.710, -0.132],
        [5.410, -0.287], [4.329, -0.490], [3.838, -0.370], [3.725, -0.241]
      svgStyle: {
        stroke: 'rgba(140, 190, 10, 0.8)',
        strokeLinecap: 'round',
        strokeLinejoin: 'round',
        strokeWidth: '10px'
      tooltip: 'A dynamic polyline marker'
      // circle marker
      id: 'circle',
      circle: 20,
      x: 2500,
      y: 1000,
      tooltip: 'A circle marker'

 * Create a new marker when the user clicks somewhere
PSV.on('click', function(e) {
    id: '#' + Math.random(),
    longitude: e.longitude,
    latitude: e.latitude,
    image: rootURL + '/assets/pin-red.png',
    width: 32,
    height: 32,
    anchor: 'bottom center',
    tooltip: 'Generated pin',
    data: {
      generated: true

 * Delete a generated marker when the user clicks on it
PSV.on('select-marker', function(marker) {
  if ( && {



Markers can be added at startup with the markers option or after load with the methods detailed further in this page.
In both case the markers attributes are :

Name type default description
id string required Unique identifier of the marker.
image string one required Path to the image representing the marker. Requires width and height.
html string HTML content of the marker.
rect int[] | Object Size of the rectangle. Eg: [10, 5] or {width: 10, height: 5}.
circle int Radius of the circle.
ellipse int[] | Object Radiuses of the ellipse. Eg: [10, 5] or {cx: 10, cy: 5}.
path string Definition of the path (0,0 will be placed at the defined x/y or longitude/latitude).
polygon_px int[][] Array of points defining the polygon in pixel coordinates on the panorama image.
Eg: [[100, 200], [150, 300], [300, 200]]
polygon_rad double[][] Same as above but coordinates are in longitude and latitude.
Eg: [[0.2, 0.4], [0.9, 1.1], [1.5, 0.7]]
polyline_px int[][] Array of points defining the polyline in pixel coordinates on the panorama image.
Eg: [[100, 200], [150, 300]]
polyline_rad double[][] Same as above but coordinates are in longitude and latitude.
Eg: [[0.2, 0.4], [0.9, 1.1]]
width & height int recommended
required for images
Size of the marker.
Ignored for polygons/polylines
x & y int required x/y or latitude/longitude Position of the marker in texture coordinates (pixels).
Ignored for polygons/polylines
latitude & longitude double Position of the marker in spherical coordinates (radians).
Ignored for polygons/polylines
scale double | double[2] 1 (constant) Scale factor multiplied by the zoom level. Provide an array of two values for min and max.
className string Optional CSS class(es) added to the marker element.
anchor string 'center center' Defines where the marker is placed toward its position. Any CSS position is valid like bottom center or 20% 80%
Ignored for polygons/polylines.
visible boolean true Is the marker visible once added. If hidden, the marker will have to be edited through getMarker method later.
tooltip string | Object Tooltip content of the marker or object defining the tooltip.
tooltip.content string Tooltip content.
tooltip.position string 'top center' Tooltip position toward the marker. Accepted values are combinations of top, center, bottom and left, center, right with the exception of center center.
style Object CSS properties to set on the marker (background, border, etc.).
svgStyle Object SVG properties to set on the marker (fill, stroke, etc.).
Only for SVG and polygons/polylines markers.
content string HTML content that will be displayed on the side panel when the marker is clicked.
data Object Any custom data you want to attach to the marker.


Check the API documentation to learn more about additional methods dedicated to the markers.


More events are also available for markers.