@mpasternacki/leaflet.locatecontrol

Leaflet.Locate

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

Tested with Leaflet 0.7 in Firefox, Webkit and mobile Webkit. Tested with Font Awesome 4.5.

Please check for breaking changes in the changelog.

Demo

Check out the demo at http://domoritz.github.io/leaflet-locatecontrol/demo/

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

The control uses Font Awesome for the icons and if you don't have it included yet, you can use the CSS from the CDN.

Then include the CSS and JavaScript files.

This example shows how to include font awesome from a CDN and the locate control files directly from github. In production, prefer using bower or the Mapbox or JsDelivr CDN.

<link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css">
<link rel="stylesheet" href="https://domoritz.github.io/leaflet-locatecontrol/dist/L.Control.Locate.min.css" />

<script src="https://domoritz.github.io/leaflet-locatecontrol/dist/L.Control.Locate.min.js" charset="utf-8"></script>

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.

Option	Type	Description	Default
position	string	Position of the control	topleft
layer	ILayer	The layer that the user's location should be drawn on.	a new layer
setView	boolean or string	Set the map view (zoom and pan) to the user's location as it updates. Options are false, 'once', 'always', and 'untilPan'	untilPan
flyTo	boolean	Smooth pan and zoom to the location of the marker. Only works in Leaflet 1.0+.	false
keepCurrentZoomLevel	boolean	Only pan when setting the view.	false
clickBehavior	object	What to do when the user clicks on the control. Has two options inView and outOfView. Possible values are stop and setView.	{inView: 'stop', outOfView: 'setView'}
returnToPrevBounds	boolean	If set, save the map bounds just before centering to the user's location. When control is disabled, set the view back to the bounds that were saved.	false
drawCircle	boolean	If set, a circle that shows the location accuracy is drawn.	true
drawMarker	boolean	If set, the marker at the users' location is drawn.	true
markerClass	class	he class to be used to create the marker.	L.CircleMarker
circleStyle	Path options	Accuracy circle style properties.	see code
markerStyle	Path options	Inner marker style properties.	see code
followCircleStyle	Path options	Changes to the accuracy circle while following. Only need to provide changes.	{}
followMarkerStyle	Path options	Changes to the inner marker while following. Only need to provide changes.	{}
icon	string	The CSS class for the icon.	fa fa-map-marker
iconLoading	string	The CSS class for the icon while loading.	fa fa-spinner fa-spin
iconElementTag	string	The element to be created for icons.	span
circlePadding	array	Padding around the accuracy circle.	[0, 0]
onLocationError	function	This even is called when the user's location is outside the bounds set on the map.	see code
onLocationOutsideMapBounds	function	Use metric units.	see code
showPopup	boolean	Display a pop-up when the user click on the inner marker.	true
strings	object	Strings used in the control. Options are title, metersUnit, feetUnit, popup, and outsideMapBoundsMsg	see code
locateOptions	Locate options	The default options passed to leaflets locate method.	see 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)
• ...

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();

Events

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

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
}}));

Developers

Run the demo locally with grunt serve 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.

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