Map plugin

The Map plugin displays a custom image (floor plan, site map, etc.) as an interactive overlay. The overlay shows the current panorama position and viewing direction, supports zoom and pan, and can include clickable hotspots.

Looking for a geographic map (OpenStreetMap, Google Maps, etc.)? Use the Plan plugin instead.

Installation

npm install @photo-sphere-viewer/map-plugin

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

Usage

The minimum configuration requires imageUrl (path to the map image) and center (the pixel coordinates of the panorama on that image).

import { Viewer } from '@photo-sphere-viewer/core';
import { MapPlugin } from '@photo-sphere-viewer/map-plugin';

const viewer = new Viewer({
    plugins: [
        MapPlugin.withConfig({
            imageUrl: 'path/to/map.jpg',
            center: { x: 785, y: 421 },
            rotation: '-12deg',
        }),
    ],
});

The north of the compass is always toward the top of the map image, before applying any rotation.

Configuration

imageUrl

string

required

URL of the map image. Not updatable after init — use setImage() instead.

center

{ x: number, y: number }

required

Pixel position of the panorama on the map image. Updatable.

rotation

number | string

default:"0"

Rotation applied to the map to align it with the panorama. Accepts radians or a degree string such as '45deg'. Updatable.

shape

'round' | 'square'

default:"'round'"

Shape of the map widget. Updatable.

size

string

default:"'200px'"

Size of the widget. Accepts any CSS length unit (px, rem, vh, etc.). Updatable.

position

string

default:"'bottom left'"

Position of the widget on screen. Accepted values: combinations of top/bottom and left/right. Updatable.

static

boolean

default:"false"

When true, the map does not rotate — only the center pin rotates to show the current viewing direction. Updatable.

overlayImage

string

SVG or image URL drawn on top of the map. Set to null to disable. Defaults to a built-in SVG. Updatable.

pinImage

string

SVG or image URL used for the central position pin. Defaults to a built-in SVG. Updatable.

pinSize

number

default:"35"

Size of the central pin in pixels. Updatable.

coneColor

string

default:"'#1E78E6'"

Color of the viewing-direction cone. Set to null to disable. Updatable.

coneSize

number

default:"40"

Size of the viewing-direction cone. Updatable.

hotspots

MapHotspot[]

default:"null"

Small dot markers on the map. Updatable. See Hotspots below. You can also call setHotspots().

Markers from the Markers plugin can appear on the map by setting their map data property to a hotspot object (without yaw, which is inferred from the marker position). The marker tooltip is reused, and clicking a map hotspot rotates the viewer to face the marker.

spotStyle

object

Default style applied to all hotspots. Updatable. Individual hotspots can override this with their own style.

Field	Type	Default	Description
`size`	`number`	`15`	Hotspot diameter
`image`	`string`	—	SVG or image URL
`color`	`string`	`'white'`	Fill color when no image
`borderSize`	`number`	`0`	Border width
`borderColor`	`string`	`null`	Border color
`hoverSize`	`number`	`null`	Size on hover
`hoverImage`	`string`	`null`	Image on hover
`hoverColor`	`string`	`null`	Color on hover
`hoverBorderSize`	`number`	`4`	Border width on hover
`hoverBorderColor`	`string`	`'rgba(255,255,255,0.6)'`	Border color on hover
`zIndex`	`number`	`null`	Stacking order

defaultZoom

number

default:"100"

Initial zoom level of the map.

maxZoom

number

default:"200"

Maximum zoom level. Updatable.

minZoom

number

default:"20"

Minimum zoom level. Updatable.

visibleOnLoad

boolean

default:"true"

Show the map when the first panorama loads.

minimizeOnHotspotClick

boolean

default:"true"

Minimize the map when the user clicks a hotspot or marker. Updatable.

buttons

object

Control which buttons are visible around the map widget.

lang

object

Localization strings merged with the main viewer lang object.

lang: {
    map: 'Map',
    mapMaximize: 'Maximize',
    mapMinimize: 'Minimize',
    mapNorth: 'Go to north',
    mapReset: 'Reset',
}

Hotspots

string

Identifier used to match select-hotspot events. Auto-generated if not provided.

yaw + distance

number

Position as an angle (radians) and a distance (pixels on the map image) from the panorama center.

x + y

number

Absolute pixel position on the map image. Use either yaw+distance or x+y.

style

object

Overrides the default spotStyle for this hotspot.

Tooltip shown when hovering the hotspot.

Methods

`setHotspots(hotspots)`

Replaces all hotspots.

mapPlugin.setHotspots([
    { id: '1', yaw: '0deg', distance: 120, tooltip: 'Hotspot one' },
    { id: '2', x: 150, y: 310 },
]);

`clearHotspots()`

Removes all hotspots.

`setImage(url, center?, rotation?)`

Replaces the map image.

mapPlugin.setImage('map2.jpg', { x: 500, y: 500 });

`setCenter(center, resetView?)`

Updates the panorama position on the map. When resetView is false (default true), the map viewport does not reposition, only the center pin moves.

mapPlugin.setCenter({ x: 500, y: 500 });

`close()` / `open()`

Toggles between closed and open states.

`maximize()` / `minimize()`

Toggles between maximized and minimized views. Has no effect when the map is closed.

`setZoom(level)`

Sets the zoom level (clamped between minZoom and maxZoom).

Events

`select-hotspot(hotspotId)`

Fired when the user clicks a hotspot.

mapPlugin.addEventListener('select-hotspot', ({ hotspotId }) => {
    console.log(`Clicked hotspot ${hotspotId}`);
});

`view-changed(view)`

Fired when the map state changes. view is 'maximized', 'normal', or 'closed'.

SCSS variables

Variable	Default	Description
`$radius`	`8px`	Corner radius (square shape only)
`$shadow`	`0 0 5px rgba(0,0,0,.7)`	Widget shadow
`$background`	`rgba(61,61,61,.7)`	Map background color
`$button-size`	`34px`	Button size
`$button-background`	`rgba(0,0,0,.5)`	Button background
`$button-color`	`core.$buttons-color`	Button icon color
`$toolbar-font`	`12px sans-serif`	Zoom indicator font
`$toolbar-text-color`	`white`	Zoom indicator text color
`$toolbar-background`	`#222`	Zoom indicator background
`$transition`	`ease-in-out .3s`	Animation transition

Get Started

Core Concepts

Adapters

Plugins

Advanced

Installation

Usage

Configuration

Hotspots

Methods

`setHotspots(hotspots)`

`clearHotspots()`

`setImage(url, center?, rotation?)`

`setCenter(center, resetView?)`

`close()` / `open()`

`maximize()` / `minimize()`

`setZoom(level)`

Events

`select-hotspot(hotspotId)`

`view-changed(view)`

SCSS variables

Build docs developers (and LLMs) love

Get Started

Core Concepts

Adapters

Plugins

Advanced

​Installation

​Usage

​Configuration

​Hotspots

​Methods

​setHotspots(hotspots)

​clearHotspots()

​setImage(url, center?, rotation?)

​setCenter(center, resetView?)

​close() / open()

​maximize() / minimize()

​setZoom(level)

​Events

​select-hotspot(hotspotId)

​view-changed(view)

​SCSS variables

Build docs developers (and LLMs) love

Installation

Usage

Configuration

Hotspots

Methods

`setHotspots(hotspots)`

`clearHotspots()`

`setImage(url, center?, rotation?)`

`setCenter(center, resetView?)`

`close()` / `open()`

`maximize()` / `minimize()`

`setZoom(level)`

Events

`select-hotspot(hotspotId)`

`view-changed(view)`

SCSS variables