maplibre-gl-streetview

A Street View control for MapLibre GL JS with support for both Google Street View and Mapillary imagery.

Features

• Dual Provider Support: Switch between Google Street View and Mapillary imagery
• Click-to-View: Click anywhere on the map to view street-level imagery
• Interactive Viewers:
  • Google Street View: Interactive 360° panoramas via iframe embed
  • Mapillary: Full MapillaryJS viewer with navigation
• Collapsible & Resizable Panel: Adjustable panel that doesn't obstruct the map
• Direction Marker: Map marker showing current view location and heading direction
• Nearest Coverage Search: Automatically finds nearby imagery when none exists at clicked location
• React Support: Full React integration with hooks and wrapper component
• TypeScript: Written in TypeScript with complete type definitions

Installation

npm install maplibre-gl-streetview

Quick Start

Vanilla JavaScript/TypeScript

import maplibregl from 'maplibre-gl';
import { StreetViewControl } from 'maplibre-gl-streetview';
import 'maplibre-gl/dist/maplibre-gl.css';
import 'maplibre-gl-streetview/style.css';
import 'mapillary-js/dist/mapillary.css'; // Required for Mapillary viewer

const map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json',
  center: [-122.4194, 37.7749],
  zoom: 14,
});

map.on('load', () => {
  const streetView = new StreetViewControl({
    googleApiKey: 'YOUR_GOOGLE_MAPS_API_KEY',
    mapillaryAccessToken: 'YOUR_MAPILLARY_ACCESS_TOKEN',
    defaultProvider: 'google',
    panelWidth: 400,
    panelHeight: 300,
  });

  map.addControl(streetView, 'top-right');

  // Listen for events
  streetView.on('locationchange', (event) => {
    console.log('Viewing:', event.state.location);
  });
});

React

import { useEffect, useRef, useState } from 'react';
import maplibregl, { Map } from 'maplibre-gl';
import { StreetViewControlReact, useStreetViewState } from 'maplibre-gl-streetview/react';
import 'maplibre-gl/dist/maplibre-gl.css';
import 'maplibre-gl-streetview/style.css';
import 'mapillary-js/dist/mapillary.css';

function App() {
  const mapContainer = useRef<HTMLDivElement>(null);
  const [map, setMap] = useState<Map | null>(null);
  const { state, toggle, setProvider } = useStreetViewState();

  useEffect(() => {
    if (!mapContainer.current) return;

    const mapInstance = new maplibregl.Map({
      container: mapContainer.current,
      style: 'https://demotiles.maplibre.org/style.json',
      center: [-122.4194, 37.7749],
      zoom: 14,
    });

    mapInstance.on('load', () => setMap(mapInstance));

    return () => mapInstance.remove();
  }, []);

  return (
    <div style={{ width: '100%', height: '100vh' }}>
      <div ref={mapContainer} style={{ width: '100%', height: '100%' }} />

      {map && (
        <StreetViewControlReact
          map={map}
          googleApiKey="YOUR_GOOGLE_MAPS_API_KEY"
          mapillaryAccessToken="YOUR_MAPILLARY_ACCESS_TOKEN"
          collapsed={state.collapsed}
          defaultProvider={state.activeProvider}
          onStateChange={(newState) => console.log(newState)}
        />
      )}
    </div>
  );
}

API Keys

Google Maps API Key

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable the Maps Embed API
4. Create an API key in Credentials

Mapillary Access Token

1. Sign up at Mapillary
2. Go to Developer Dashboard
3. Create a new application
4. Copy your client access token

Options

StreetViewControlOptions

| Option | Type | Default | Description | |--------|------|---------|-------------| | collapsed | boolean | true | Start with panel collapsed | | position | string | 'top-right' | Control position on map | | title | string | 'Street View' | Panel header title | | panelWidth | number | 400 | Panel width in pixels | | panelHeight | number | 300 | Panel height in pixels | | defaultProvider | 'google' \| 'mapillary' | 'google' | Default imagery provider | | googleApiKey | string | - | Google Maps API key | | mapillaryAccessToken | string | - | Mapillary access token | | clickToView | boolean | true | Enable click-to-view on map | | showMarker | boolean | true | Show marker at view location | | maxSearchRadius | number | 100 | Max search radius for nearest imagery (meters) | | markerOptions | MarkerOptions | - | Customize marker appearance |

MarkerOptions

| Option | Type | Default | Description | |--------|------|---------|-------------| | color | string | '#ff5722' | Marker dot color | | showDirection | boolean | true | Show direction indicator | | directionColor | string | '#1976d2' | Direction arrow color |

Events

| Event | Description | |-------|-------------| | expand | Panel expanded | | collapse | Panel collapsed | | statechange | Any state change | | providerchange | Provider switched | | locationchange | View location changed | | headingchange | View heading changed | | load | Imagery loaded | | error | Error occurred |

streetView.on('statechange', (event) => {
  console.log('State:', event.state);
});

streetView.on('error', (event) => {
  console.error('Error:', event.error);
});

Methods

| Method | Description | |--------|-------------| | toggle() | Toggle panel visibility | | expand() | Expand the panel | | collapse() | Collapse the panel | | setProvider(provider) | Switch to a provider | | showStreetView(lngLat) | Show street view at location | | clearStreetView() | Clear current street view | | getState() | Get current state |

React Hooks

useStreetViewState

State management hook for the street view control.

const {
  state,
  toggle,
  expand,
  collapse,
  setProvider,
  setLoading,
  reset,
} = useStreetViewState({ collapsed: true });

useStreetViewProvider

Provider configuration helper hook.

const {
  availableProviders,
  isProviderAvailable,
  getDefaultProvider,
  hasAnyProvider,
} = useStreetViewProvider({
  google: { enabled: true, apiKey: 'key' },
  mapillary: { enabled: true, accessToken: 'token' },
});

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm test

# Build library
npm run build

# Build examples
npm run build:examples

Environment Variables

Create a .env file in the project root:

VITE_GOOGLE_MAPS_API_KEY=your_google_api_key
VITE_MAPILLARY_ACCESS_TOKEN=your_mapillary_token

Live Demo

Visit the GitHub Pages demo to see the plugin in action.

License

MIT License - see LICENSE for details.

Author

Qiusheng Wu

Contributing

Contributions are welcome! Please open an issue or submit a pull request.