maplibre-pegman

A MapLibre GL JS plugin that allows easy integration with the Google StreetView Service API via a draggable Pegman control.

How to use

1. Include dependencies

<!-- MapLibre GL JS -->
<link rel="stylesheet" href="https://unpkg.com/maplibre-gl@3/dist/maplibre-gl.css" />
<script src="https://unpkg.com/maplibre-gl@3/dist/maplibre-gl.js"></script>

<!-- interact.js (required for drag-and-drop) -->
<script src="https://unpkg.com/[email protected]/dist/interact.min.js"></script>

Note: If you omit the interact.js and Google Maps script tags, they will be lazy-loaded automatically on first user interaction.

2. Include the plugin

Via CDN / script tag

<link rel="stylesheet" href="https://unpkg.com/maplibre-pegman/maplibre-pegman.css" />
<script src="https://unpkg.com/maplibre-pegman/maplibre-pegman.js"></script>

Via npm

npm install maplibre-pegman

const MaplibrePegman = require('maplibre-pegman');
// or
import MaplibrePegman from 'maplibre-pegman';

Don't forget to include the CSS file as well (import it via your bundler or add a <link> tag).

3. Add the control to your map

var map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json',
  center: [9.5, 45],
  zoom: 5
});

var pegmanControl = new MaplibrePegman({
  position: 'top-right',
  theme: 'leaflet-pegman-v3-default',
  apiKey: 'YOUR_GOOGLE_MAPS_API_KEY',
});

pegmanControl.addTo(map);

Options

| Option | Type | Default | Description | | ------------ | -------- | ------------------------------ | ------------------------------------------------------------------------ | | position | String | 'top-right' | Position of the control: 'top-left', 'top-right', 'bottom-left', 'bottom-right' | | theme | String | 'leaflet-pegman-v3-default' | CSS theme class. 'leaflet-pegman-v3-default' (40px) or 'leaflet-pegman-v3-small' (30px) | | debug | Boolean| false | Enable console logging | | apiKey | String | '' | Google Maps API key (required for StreetView) | | libraries | String | '' | Comma-separated list of additional Google Maps libraries (e.g. 'geometry') | | pano | Object | {enableCloseButton: true, ...} | Options passed to google.maps.StreetViewPanorama | | panoDiv | String | null | CSS selector for a detached panorama <div> (e.g. '#panorama'). If omitted, the panorama overlays the map. |

Events

The control fires events with the prefix svpc_:

| Event | Description | | ------------------------------- | -------------------------------- | | svpc_pegman-dragging | Pegman drag started | | svpc_pegman-dragged | Pegman drag ended | | svpc_pegman-added | Pegman marker placed on map | | svpc_pegman-removed | Pegman marker removed from map | | svpc_streetview-shown | StreetView layer activated | | svpc_streetview-hidden | StreetView layer deactivated | | svpc_dropzone-actived | Map drop zone activated | | svpc_dropzone-drag-entered | Pegman dragged into map | | svpc_dropzone-drag-leaved | Pegman dragged out of map | | svpc_dropzone-drop | Pegman dropped on map | | svpc_dropzone-deactivated | Map drop zone deactivated |

pegmanControl.on('svpc_pegman-added', function() {
  console.log('Pegman placed on map!');
});

API Methods

| Method | Description | | ---------------------------------- | ----------------------------------------------- | | addTo(map) | Add the control to a MapLibre map | | pegmanAdd() | Place the pegman marker at stored coordinates | | pegmanRemove() | Remove the pegman marker from the map | | findStreetViewData(lat, lng) | Search for StreetView data at the given location | | toggleStreetViewLayer() | Toggle the StreetView mode on/off | | showStreetViewLayer() | Activate StreetView mode | | hideStreetViewLayer() | Deactivate StreetView mode | | openStreetViewPanorama() | Show the panorama div | | closeStreetViewPanorama() | Hide the panorama div | | clear() | Remove pegman, hide layer, close panorama |

Requirements

• MapLibre GL JS >= 3.0.0
• interact.js 1.2.9 (auto-loaded if not present)
• Google Maps JavaScript API v3 with a valid API key

Notes

• Google StreetView coverage tile overlay is not available in the MapLibre version because Google's tile endpoint does not serve CORS headers. The core StreetView panorama functionality (drag pegman, click map, open panorama) works fully.
• Press Escape to close the panorama and remove the pegman marker.

License

GPL-3.0+