# MarkersPlugin

API Documentation

Displays various markers/hotspots on the viewer.

This plugin is available in the core photo-sphere-viewer package in dist/plugins/markers.js and dist/plugins/markers.css.

# Usage

The plugin provides a powerful markers system allowing to define points of interest on the panorama with optional tooltip and description. Markers can be dynamically added/removed and you can react to 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 polygonPx/polygonRad/polylinePx/polylineRad attribute

Markers can be added at startup with the markers option or after load with the various methods.

const viewer = new PhotoSphereViewer.Viewer({
  plugins: [
    [PhotoSphereViewer.MarkersPlugin, {
      markers: [ 
          id: 'new-marker',
          longitude: '45deg',
          latitude: '0deg',
          image: 'assets/pin-red.png',

const markersPlugin = viewer.getPlugin(PhotoSphereViewer.MarkersPlugin);

markersPlugin.on('select-marker', (e, marker) => {
    id: marker.id,
    image: 'assets/pin-blue.png'

# Example

The following example contains all types of markers. Click anywhere on the panorama to add a red marker, right-click to change it's color and double-click to remove it.

# Markers definition

One of these options is required.

Name Type Description
image string Path to the image representing the marker. Requires width and height to be defined.
html string HTML content of the marker. It is recommended to define width and height.
square integer Size of the square.
rect integer[2] |
Size of the rectangle.
circle integer Radius of the circle.
ellipse integer[2] |
Radiuses of the ellipse.
path string Definition of the path (0,0 will be placed at the defined x/y or longitude/latitude).
polygonPx integer[2][] Array of points defining the polygon in pixel coordinates on the panorama image.
polygonRad double[2][] Same as above but coordinates are in longitude and latitude.
polylinePx integer[2][] Same as polygonPx but generates a polyline.
polylineRad double[2][] Same as polygonRad but generates a polyline.

Examples :

  image: 'pin-red.png',
  html: 'Click here',
  square: 10,
  rect: [10, 5],
  rect: {width: 10, height: 5},
  circle: 10,
  ellipse: [10, 5],
  ellipse: {cx: 10, cy: 5},
  path: 'M 0 0 L 60 60 L 60 0 L 0 60 L 0 0',
  polygonPx: [[100, 200], [150, 300], [300, 200]],
  polygonRad: [[0.2, 0.4], [0.9, 1.1], [1.5, 0.7]],
  polylinePx: [[100, 200], [150, 300]],
  polylineRad: [[0.2, 0.4], [0.9, 1.1]],


Texture coordinates are not applicable to cubemaps.

# Markers options

# id (required)

  • type: string

Unique identifier of the marker.

# x & y or latitude & longitude (required)

  • type: integer or double

Position of the marker in texture coordinates (pixels) or spherical coordinates (radians). (This option is ignored for polygons and polylines)

  • type: integer

Size of the marker. (This option is ignored for polygons and polylines)

# scale

  • type: double | double[]

Scale factor multiplied by the zoom level. Provide an array of two values for min and max. By default the scale is constant. (This option is ignored for polygons and polylines)

scale: 1 // the marker is scalling with the zoom level (from 0 to 100%)

scale: [0.5, 1] // at minimum zoom level the marker is half its size at maximum zoom level

# className

  • type: string

CSS class(es) added to the marker element.

# style

  • type: object

CSS properties to set on the marker (background, border, etc.).

style: {
  backgroundColor: 'rgba(0, 0, 0, 0.5)',
  cursor         : 'help'

# svgStyle

  • type: object

SVG properties to set on the marker (fill, stroke, etc.). Only for SVG and polygons/polylines markers.

svgStyle: {
  fill       : 'rgba(0, 0, 0, 0.5)',
  stroke     : '#ff0000',
  strokeWidth: '2px'

Image and pattern background

You can define complex SVG backgrounds such as images by using a pattern definition.

First declare the pattern somewhere in your page :

<svg id="patterns">
    <!-- define pattern origin on its center -->
    <pattern id="image" x="256" y="256" width="512" height="512" patternUnits="userSpaceOnUse">
      <image href="my-image.jpg" x="0" y="0" width="512" height="512"/>

And use it in your marker : fill: 'url(#image)'.

# anchor

  • type: string
  • default: 'center center'

Defines where the marker is placed toward its defined position. Any CSS position is valid like bottom center or 20% 80%. (This option is ignored for polygons and polylines)

# visible

  • type: boolean
  • default: true

Initial visibility of the marker.

# tooltip

  • type: string | {content: string, position: string}
  • default: {content: null, position: 'top center'}

Tooltip content and position. Accepted positions are combinations of top, center, bottom and left, center, right with the exception of center center.

tooltip: 'This is a marker' // tooltip with default position

tooltip: { // tooltip with custom position
  content : 'This is marker',
  position: 'bottom left'

# content

  • type: string

HTML content that will be displayed on the side panel when the marker is clicked.

# hideList

  • type: boolean
  • default: false

Hide the marker in the markers list.

# data

  • type: any

Any custom data you want to attach to the marker.

# Configuration

# lang

  • type: object
  • default:
lang: {
  markers : 'Markers',
  markersList : 'Markers list',

Note: this option is not part of the plugin but is merged with the main lang object.

# clickEventOnMarker

  • type: boolean
  • default: false

If a click event is triggered on the viewer additionally to the select-marker event.

# Methods

# addMarker(properties)

Adds a new marker to the viewer.

  id: 'new-marker',
  longitude: '45deg',
  latitude: '0deg',
  image: 'assets/pin-red.png',

# clearMarkers()

Removes all markers.

# getCurrentMarker(): Marker

Returns the last marker clicked by the user.

# gotoMarker(id, speed): Animation

Moves the view to center a specific marker, with optional animation.

markersPlugin.gotoMarker('marker-1', 1500)
  .then(() => /* animation complete */);

# hideMarker(id) | showMarker(id) | toggleMarker(id)

Changes the visiblity of a marker.

# removeMarker(id)

Removes a marker.

# setMarkers(properties[])

Replaces all markers by new ones.

# updateMarker(properties)

Updates a marker with new properties. The type of marker cannot be changed.

  id: 'existing-marker',
  image: 'assets/pin-blue.png'

# Events

# over-marker(marker) | leave-marker(marker)

Triggered when the user puts the cursor hover or away a marker.

markersPlugin.on('over-marker', (e, marker) => {
  console.log(`Cursor is over marker ${marker.id}`);

# select-marker(marker, data)

Triggered when the user clicks on a marker. The data object indicates if the marker was selected with a double a click on a right click.

# unselect-marker(marker)

Triggered when a marker was selected and the user clicks elsewhere.