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

Check out the demo page with three different examples (Leaflet UMD, Leaflet ESM, Mapbox UMD).

Basic Usage

$3

1. Get the JavaScript and CSS files
2. Include the files in your project
3. Initialize the plugin

#### Get the JavaScript and CSS files

For production:

The best way to get the plugin is via npm:

``bash
npm install leaflet.locatecontrol
`

Alternatively, you can use the JsDelivr CDN (see instructions below) or download the files from this repository.

For development:

Clone the repository to work with the source code:

`bash
git clone https://github.com/domoritz/leaflet-locatecontrol
`

The source files are in src/ and the built distribution files are in dist/.

#### Include the JavaScript and CSS files in your project

##### 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.

`html


`

##### With npm

`ts
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
`

If you are using a bundler or esm, use

`ts
import { LocateControl } from "leaflet.locatecontrol";
import "leaflet.locatecontrol/dist/L.Control.Locate.min.css";
`

Then use new LocateControl() instead of L.control.locate().

#### Add the following snippet to your map initialization

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

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

$3

The locate controls inherits options from Leaflet Controls.

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

`js
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', 'untilPan', or 'untilPanOrZoom' | 'untilPanOrZoom' |
| flyTo | boolean | Smooth pan and zoom to the location of the marker. Only works in Leaflet 1.0+. | false |
| keepCurrentZoomLevel | boolean or Array | Only pan when setting the view. Set to true to always keep the current zoom, or provide a zoom range like [13, 18] to only keep the zoom when it's within that range. Outside the range, the map will zoom normally. | false |
| initialZoomLevel | false or integer | After activating the plugin by clicking on the icon, zoom to the selected zoom level, even when keepCurrentZoomLevel is true. Set to false to disable this feature. | false |
| clickBehavior | object | What to do when the user clicks on the control. Has three options inView, inViewNotFollowing and outOfView. Possible values are stop and setView, or the name of a behaviour to inherit from. | {inView: 'stop', outOfView: 'setView', inViewNotFollowing: 'inView'} |
| 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 |
| cacheLocation | boolean | Keep a cache of the location after the user deactivates the control. If set to false, the user has to wait until the locate API returns a new location before they see where they are again. | true |
| showCompass | boolean | Show the compass bearing on top of the location marker | true |
| 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 | The class to be used to create the marker. | LocationMarker |
| compassClass | class | The class to be used to create the marker. | CompassMarker |
| circleStyle | Path options | Accuracy circle style properties. | see code |
| markerStyle | Path options | Inner marker style properties. Only works if your marker class supports setStyle. | see code |
| compassStyle | Path options | Triangle compass heading marker style properties. Only works if your marker class supports setStyle. | 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. | {} |
| followCompassStyle | Path options | Changes to the compass marker while following. Only need to provide changes. | {} |
| icon | string | The CSS class for the icon. | leaflet-control-locate-location-arrow |
| iconLoading | string | The CSS class for the icon while loading. | leaflet-control-locate-spinner |
| iconElementTag | string | The element to be created for icons. | span |
| textElementTag | string | The element to be created for the text. | small |
| circlePadding | array | Padding around the accuracy circle. | [0, 0] |
| createButtonCallback | function | This callback can be used in case you would like to override button creation behavior. | see code |
| getLocationBounds | function | This callback can be used to override the viewport tracking behavior. | see code |
| onLocationError | function | This even is called when the user's location is outside the bounds set on the map. | see code |
| metric | boolean | Use metric units. | true |
| onLocationOutsideMapBounds | function | Called when the user's location is outside the bounds set on the map. Called repeatedly when the user's location changes. | 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, text, metersUnit, feetUnit, popup and outsideMapBoundsMsg | see code |
| strings.popup | string or function | The string shown as popup. May contain the placeholders {distance} and {unit}. If this option is specified as function, it will be executed with a single parameter {distance, unit} and expected to return a string. | 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

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

To add text next to the location icon:

`js
let lc = L.control
.locate({
strings: {
title: "Show me where I am, yo!",
text: "Locate me"
}
})
.addTo(map);
`

Screenshot

!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

$3

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

`js
// create control and add to map
let 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().

$3

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.

The control also fires a locationtimeout event when geolocation timeouts occur in watch mode. This is useful for providing custom feedback to users when location acquisition takes longer than expected:

`js
map.on("locationtimeout", function (e) {
console.log("Location timeout count:", e.count);
// Provide custom feedback or retry logic
});
`

Note: When watch: true (the default), timeout errors don't stop the location tracking - the browser will automatically retry. After 3 consecutive timeouts, the control displays a visual indicator (orange spinner) to inform users that location acquisition is taking longer than usual.

$3

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.

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

let lc = new L.Control.MyLocate();
`

$3

#### How do I set the maximum zoom level?

Set the maxZoom in locateOptions (only applies when keepCurrentZoomLevel is false or when the current zoom is outside a specified range).

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

You can also use keepCurrentZoomLevel: [13, 18] to only keep zoom when it's between levels 13-18, but zoom normally outside that range:

`js
map.addControl(
L.control.locate({
keepCurrentZoomLevel: [13, 18],
locateOptions: {
maxZoom: 16
}
})
);
`

#### How do I enable high accuracy?

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

`js
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.

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

Developers

Run the demo locally with npm start and then open http://localhost:9000.

The development server is a native Node.js script (scripts/server.js) that serves the project on port 9000. It does not require any external dependencies. Note that modern browsers treat localhost as a secure context, so HTTPS is not required for the Geolocation API to work.

To generate the minified JS and CSS files, run npm run build.

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 lint:fix to automatically fix style and linting issues.

Making a release (only core developer)

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

$3

- 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