Brings the basic functionality of Google Maps Gesture Handling into Leaflet. Prevents users from getting trapped on the map when scrolling a long page.
Clone or download
Latest commit 6256797 Sep 27, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist v1.1.8 Sep 27, 2018
examples reinstate ajhbhs edits Jul 31, 2018
src v1.1.8 Sep 27, 2018
.gitignore giuly90 - bootratp patch. Fix warning message z-index Aug 9, 2018
.prettierrc Add support for use as an npm module Jul 11, 2018
LICENSE Create LICENSE Mar 15, 2018
README.md v1.1.8 Sep 27, 2018
gulpfile.js v1.1.3 - now avail as npm module Jul 16, 2018
package-lock.json Remove extra decleration of isScrolling Aug 29, 2018
package.json v1.1.8 Sep 27, 2018

README.md

Leaflet.GestureHandling

Version 1.1.8

Brings the basic functionality of Google Maps Gesture Handling into Leaflet.

Prevents users from getting trapped on the map when scrolling a long page.

On Desktop

alt text

  • The map ignores the mouse scroll wheel.
  • The user is prompted to use ctrl+scroll to zoom the map.

On Mobile / Touch devices

alt text

  • The map ignores single fingered dragging.
  • The user is prompted to use two fingers to pan the map.

Demo

View demo

Install

The latest leaflet-gesture-handling can be downloaded from the dist folder.

Usage

Include the css and js file after leaflet.js.

<link rel="stylesheet" href="css/leaflet-gesture-handling.min.css" type="text/css">
<script src="js/leaflet-gesture-handling.min.js"></script>

Or load this directly from UNPKG:

<link rel="stylesheet" href="//unpkg.com/leaflet-gesture-handling/dist/leaflet-gesture-handling.min.css" type="text/css">
<script src="//unpkg.com/leaflet-gesture-handling"></script>

Set gestureHandling: true in your map initialization script.

var map = L.map("map", {
    center: [-25.2702, 134.2798],
    zoom: 3,
    gestureHandling: true
});

Use as a module

If you are using a bundler such as Webpack or Parcel, you can load the library as a module. First install the module with:

npm install leaflet-gesture-handling

Then include the module and CSS in your source:

import * as L from "leaflet";
import { GestureHandling } from "leaflet-gesture-handling";

import "leaflet/dist/leaflet.css";
import "leaflet-gesture-handling/dist/leaflet-gesture-handling.css";

Then attach it as a handler to the map:

L.Map.addInitHook("addHandler", "gestureHandling", GestureHandling);

const map = L.map("map", {
    center: [50.36, -4.747],
    zoom: 3,
    gestureHandling: true
});

Multi Language and Custom Text

The plugin will auto detect a users language from the browser setting and show the appropriate translation. 52 languages are supported without you needing to do anything.

However if you wish to override this, you can set your own text by supplying gestureHandlingOptions and a text option as shown below. You must specify text for touch, scroll and scrollMac.

var map = L.map("map", {
    center: [-25.2702, 134.2798],
    zoom: 3,
    gestureHandling: true,
    gestureHandlingOptions: {
        text: {
            touch: "Hey bro, use two fingers to move the map",
            scroll: "Hey bro, use ctrl + scroll to zoom the map",
            scrollMac: "Hey bro, use \u2318 + scroll to zoom the map"
        }
    }
});

*Note: Earlier versions used a property called gestureHandlingText for this which still works.

Other Options

To pass in options use the property: gestureHandlingOptions.

  • duration : (int) time in ms before the message should disappear. default: 1000 (1 sec)
var map = L.map("map", {
    center: [-25.2702, 134.2798],
    zoom: 3,
    gestureHandling: true,
    gestureHandlingOptions: {
        duration: 5000 //5 secs
    }
});

Useful info

GestureHandling disables the following map attributes.

  • dragging
  • tap
  • scrollWheelZoom

They are temporarily enabled for the duration the user scrolls with ctrl+mousewheel or uses two fingers to pan the map on mobile.

Compatibility with other plugins

I have added compatibility with Leaflet-MiniMap. It allows the user to still pan around the minimap with a single finger.

If there's any other plugins you'd like this to work with, let me know or submit a pull request.

License

MIT