Packages

Most users only need the ol, google-maps, or leaflet package. Each re-exports everything from core.

Requirements

• A modern browser with WebGL and getUserMedia (webcam permission).
• OpenLayers 10.x, Google Maps JavaScript API, or Leaflet 1.9.x.

Install

OpenLayers:

npm install @map-gesture-controls/ol ol

Google Maps:

npm install @map-gesture-controls/google-maps @googlemaps/js-api-loader
npm install -D @types/google.maps

Leaflet:

npm install @map-gesture-controls/leaflet leaflet
npm install -D @types/leaflet

Publish flow (maintainers): run npm run build so the dist/ folder exists before npm publish (this repo does not commit dist/).

Usage

OpenLayers

You need a container element in your HTML (e.g. <div id="map"></div>) and an OpenLayers Map instance:

import Map from 'ol/Map.js';
import View from 'ol/View.js';
import TileLayer from 'ol/layer/Tile.js';
import OSM from 'ol/source/OSM.js';
import { fromLonLat } from 'ol/proj.js';
import { GestureMapController } from '@map-gesture-controls/ol';
import '@map-gesture-controls/ol/style.css';

const map = new Map({
  target: 'map',
  layers: [new TileLayer({ source: new OSM() })],
  view: new View({ center: fromLonLat([0, 0]), zoom: 2 }),
});

const controller = new GestureMapController({ map });

// Must be called from a user gesture (e.g. button click) for webcam permission
await controller.start();

controller.stop(); // tear down webcam and overlay

Google Maps

import { Loader } from '@googlemaps/js-api-loader';
import { GestureMapController } from '@map-gesture-controls/google-maps';
import '@map-gesture-controls/google-maps/style.css';

const loader = new Loader({ apiKey: 'YOUR_API_KEY', version: 'weekly' });
const { Map } = await loader.importLibrary('maps');

const map = new Map(document.getElementById('map')!, {
  center: { lat: 0, lng: 0 },
  zoom: 2,
  mapId: 'YOUR_MAP_ID', // enables vector maps (required for rotation)
});

const controller = new GestureMapController({ map });

await controller.start();

controller.stop();

You need a Google Maps API key and a Map ID from the Google Cloud Console. Create the Map ID with the Vector map type to enable rotation support. For local development, add both to a .env file:

VITE_GOOGLE_MAPS_API_KEY=your_api_key
VITE_GOOGLE_MAPS_MAP_ID=your_map_id

See the Google Maps Getting Started guide for full setup details.

Leaflet

import L from 'leaflet';
import 'leaflet/dist/leaflet.css';
import { GestureMapController } from '@map-gesture-controls/leaflet';
import '@map-gesture-controls/leaflet/style.css';

const map = L.map('map').setView([52.37, 4.9], 10);
L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
  attribution:
    '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',
}).addTo(map);

const controller = new GestureMapController({ map });

await controller.start();

controller.stop();

No API key needed. Leaflet uses OpenStreetMap tiles by default. Rotation is supported via CSS transforms on the map pane.

See the Leaflet Getting Started guide for full setup details.

Optional config: webcam, tuning, and debug. See the Configuration section below.

Configuration

All options are optional. Pass only the keys you want to override; the rest use sensible defaults.

// `map` is your ol/Map or google.maps.Map instance (see Usage above)
const controller = new GestureMapController({
  map,
  webcam: {
    position: 'top-left', // move overlay to top-left corner
    width: 240, // narrower overlay
    height: 180,
    margin: 24, // 24 px from viewport edges
    opacity: 0.7,
  },
  tuning: {
    actionDwellMs: 40, // faster gesture confirmation
    releaseGraceMs: 80, // shorter grace period
    panDeadzonePx: 0, // direct panning for slow movement
  },
  debug: true, // log gesture mode to console
});

webcam options (WebcamConfig)

tuning options (TuningConfig)