Leaflet.Locate

A useful control to geolocate the user with many options. Official Leaflet and MapBox plugin.

Tested with Leaflet 1.9.2 and Mapbox.js 3.3.1 in Firefox, Chrome and Safari.

Please check for breaking changes in the changelog.

Demo

• Demo with Leaflet
• Demo with Mapbox.js

Basic Usage

Set up:

tl;dr

1. Get CSS and JavaScript files
2. Include CSS and JavaScript files
3. Initialize plugin

Download JavaScript and CSS files

For testing purposes and development, you can use the latest version directly from my repository.

For production environments, use Bower and run bower install leaflet.locatecontrol or download the files from this repository. Bower will always download the latest version and keep the code up to date. The original JS and CSS files are in \src and the minified versions suitable for production are in \dist.

You can also get the latest version of the plugin with npm. This plugin is available in the npm repository. Just run npm install leaflet.locatecontrol.

The control is available from JsDelivr CDN. If you don't need the latest version, you can use the mapbox CDN.

Add the JavaScript and CSS files

Then include the CSS and JavaScript files.

With CDN

In this example, we are loading the files from the JsDelivr CDN. In the URLs below, replace [VERSION] with the latest release number or remove @[VERSION] to always use the latest version.

With npm

import "leaflet.locatecontrol"; // Import plugin
import "leaflet.locatecontrol/dist/L.Control.Locate.min.css"; // Import styles
import L from "leaflet"; // Import L from leaflet to start using the plugin

Add the following snippet to your map initialization:

This snippet adds the control to the map. You can pass also pass a configuration.

L.control.locate().addTo(map);

Possible options

The locate controls inherits options from Leaflet Controls.

To customize the control, pass an object with your custom options to the locate control.

L.control.locate(OPTIONS).addTo(map);

Possible options are listed in the following table. More details are in the code.

For example, to customize the position and the title, you could write

var lc = L.control
  .locate({
    position: "topright",
    strings: {
      title: "Show me where I am, yo!"
    }
  })
  .addTo(map);

Screenshot

Users

Sites that use this locate control:

• OpenStreetMap on the start page
• MapBox
• wheelmap.org
• OpenMensa
• Maps Marker Pro (WordPress plugin)
• Bikemap
• MyRoutes
• NearbyWiki
• ...

Advanced Usage

Methods

You can call start() or stop() on the locate control object to set the location on page load for example.

// create control and add to map
var lc = L.control.locate().addTo(map);

// request location update and set location
lc.start();

You can keep the plugin active but stop following using lc.stopFollowing().

Events

You can leverage the native Leaflet events locationfound and locationerror to handle when geolocation is successful or produces an error. You can find out more about these events in the Leaflet documentation.

Additionally, the locate control fires locateactivate and locatedeactivate events on the map object when it is activated and deactivated, respectively.

Extending

To customize the behavior of the plugin, use L.extend to override start, stop, _drawMarker and/or _removeMarker. Please be aware that functions may change and customizations become incompatible.

L.Control.MyLocate = L.Control.Locate.extend({
  _drawMarker: function () {
    // override to customize the marker
  }
});

var lc = new L.Control.MyLocate();

FAQ

How do I set the maximum zoom level?

Set the maxZoom in locateOptions (keepCurrentZoomLevel must not be set to true).

map.addControl(
  L.control.locate({
    locateOptions: {
      maxZoom: 10
    }
  })
);

How do I enable high accuracy?

To enable high accuracy (GPS) mode, set the enableHighAccuracy in locateOptions.

map.addControl(
  L.control.locate({
    locateOptions: {
      enableHighAccuracy: true
    }
  })
);

Safari does not work with Leaflet 1.7.1

This is a bug in Leaflet. Disable tap to fix it for now. See this issue for details.

let map = new L.Map('map', {
    tap: false,
    ...
});

Developers

Run the demo locally with yarn start or npm run start and then open localhost:9000/demo/index.html.

To generate the minified JS and CSS files, use grunt and run grunt. However, don't include new minified files or a new version as part of a pull request. If you need SASS, install it with brew install sass/sass/sass.

Prettify and linting

Before a Pull Request please check the code style.

Run npm run lint to check if there are code style or linting issues.

Run npm run:fix to automatically fix style and linting issues.

Making a release (only core developer)

A new version is released with npm run bump:minor. Then push the new code with git push && git push --tags and publish to npm with npm publish.

Terms

• active: After we called map.locate() and before map.stopLocate(). Any time, the map can fire the locationfound or locationerror events.
• following: Following refers to whether the map zooms and pans automatically when a new location is found.

Thanks

To all contributors and issue reporters.

License

MIT

SVG icons from Font Awesome v5.15.4: Creative Commons Attribution 4.0