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 defined with the polygon_px or polygon_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.

</> See source



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]]
width & height int recommended
required for images
Size of the marker.
Ignored for polygons
x & y int required x/y or latitude/longitude Position of the marker in texture coordinates (pixels).
Ignored for polygons
latitude & longitude double Position of the marker in spherical coordinates (radians).
Ignored for polygons
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.
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 markers.
content string HTML content that will be displayed on the side panel when the marker is clicked.


.addMarker(properties [, render])

Adds a new marker to the viewer. The method returns an object representing the actual marker with all properties and an additional $el attribute, referencing the HTMLElement in the viewer.

Set the render flag to false to postpone viewer update (usefull when adding a batch of markers), call render() method when done.

  id: 'marker-1',
  image: 'path/to/pin.png',
  width: 32,
  height: 32,
  x: 500,
  y: 1000

.updateMarker(marker [, render])

Updates the existing marker with the same id. Every property can be changed but you can't change its type (Eg: image to html).

// update by defining new properties
  id: 'marker-1',
  x: 1000

// update via reference
var marker = viewer.addMarker({ ... });
marker.x = 1000;


Returns the internal marker object for a marker id.

var marker = viewer.getMarker('marker-1');


Returns the last marker selected by the user or null.

var currentMarker = viewer.getCurrentMarker();

.removeMarker(marker | markerId [, render])

Removes a marker from the viewer.


.gotoMarker(marker | markerId [, duration | speed])

Rotate the view to face the marker. If the last parameter is provided (see the animate() method) the camera will rotate smoothly to the the marker.

viewer.gotoMarker('marker-1', 1500);


Removes all markers.

.hideMarker(marker | markerId) / .showMarker(marker | markerId) / .toggleMarker(marker | markerId)


select-marker [marker]

Triggered when the user click on a marker. The marker can be retrieved from outside the event handler with getCurrentMarker() method.

viewer.on('select-marker', function(marker) {
  alert('Select ' +;

unselect-marker [marker]

Triggered when a marker was selected a the user click elsewhere.

viewer.on('unselect-marker', function(marker) {
  alert( + ' was selected');

render-markers-list [markers]

Used to alter the list of markers displayed on the side-panel.

viewer.on('render-markers-list', function(markers) {
  return markers.slice(0, 5);