{"id":13554729,"url":"https://github.com/domoritz/leaflet-locatecontrol","last_synced_at":"2025-05-13T20:12:01.226Z","repository":{"id":5344896,"uuid":"6530634","full_name":"domoritz/leaflet-locatecontrol","owner":"domoritz","description":"A leaflet control to geolocate the user.","archived":false,"fork":false,"pushed_at":"2025-04-29T22:59:06.000Z","size":4427,"stargazers_count":845,"open_issues_count":24,"forks_count":268,"subscribers_count":33,"default_branch":"gh-pages","last_synced_at":"2025-05-13T02:11:47.582Z","etag":null,"topics":["leaflet","leaflet-control","location","mapbox"],"latest_commit_sha":null,"homepage":"https://domoritz.github.io/leaflet-locatecontrol/demo/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/domoritz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2012-11-04T12:53:00.000Z","updated_at":"2025-05-09T16:02:10.000Z","dependencies_parsed_at":"2025-02-04T18:06:32.935Z","dependency_job_id":"f191266e-515e-4bea-9e65-5ae280976341","html_url":"https://github.com/domoritz/leaflet-locatecontrol","commit_stats":{"total_commits":431,"total_committers":62,"mean_commits":6.951612903225806,"dds":"0.28306264501160094","last_synced_commit":"688fb133f820f873b3898043f4f1260695edc4df"},"previous_names":[],"tags_count":96,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/domoritz%2Fleaflet-locatecontrol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/domoritz%2Fleaflet-locatecontrol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/domoritz%2Fleaflet-locatecontrol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/domoritz%2Fleaflet-locatecontrol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/domoritz","download_url":"https://codeload.github.com/domoritz/leaflet-locatecontrol/tar.gz/refs/heads/gh-pages","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253856661,"owners_count":21974582,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["leaflet","leaflet-control","location","mapbox"],"created_at":"2024-08-01T12:02:53.774Z","updated_at":"2025-05-13T20:12:01.170Z","avatar_url":"https://github.com/domoritz.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","others"],"sub_categories":[],"readme":"# Leaflet.Locate\n\n[![npm version](https://badge.fury.io/js/leaflet.locatecontrol.svg)](http://badge.fury.io/js/leaflet.locatecontrol)\n[![jsDelivr Hits](https://data.jsdelivr.com/v1/package/npm/leaflet.locatecontrol/badge?style=rounded)](https://www.jsdelivr.com/package/npm/leaflet.locatecontrol)\n\nA useful control to geolocate the user with many options. Official [Leaflet](http://leafletjs.com/plugins.html#geolocation) and [MapBox plugin](https://www.mapbox.com/mapbox.js/example/v1.0.0/leaflet-locatecontrol/).\n\nTested with [Leaflet](http://leafletjs.com/) 1.9.2 and [Mapbox.js](https://docs.mapbox.com/mapbox.js/) 3.3.1 in Firefox, Chrome and Safari.\n\nPlease check for [breaking changes in the changelog](https://github.com/domoritz/leaflet-locatecontrol/blob/gh-pages/CHANGELOG.md).\n\n## Demo\n\n- [Demo with Leaflet](https://domoritz.github.io/leaflet-locatecontrol/demo/)\n- [Demo with Mapbox.js](https://domoritz.github.io/leaflet-locatecontrol/demo_mapbox/)\n\n## Basic Usage\n\n### Set up:\n\n1. Get CSS and JavaScript files\n2. Include CSS and JavaScript files\n3. Initialize plugin\n\n#### Download JavaScript and CSS files\n\nFor testing purposes and development, you can use the latest version directly from my repository.\n\nFor production environments, use [Bower](http://bower.io/) and run `bower install leaflet.locatecontrol` or [download the files from this repository](https://github.com/domoritz/leaflet-locatecontrol/archive/gh-pages.zip). Bower will always download the latest version and keep the code up to date. The original JS and CSS files are in [`\\src`](https://github.com/domoritz/leaflet-locatecontrol/tree/gh-pages/src) and the minified versions suitable for production are in [`\\dist`](https://github.com/domoritz/leaflet-locatecontrol/tree/gh-pages/dist).\n\nYou can also get the latest version of the plugin with [npm](https://www.npmjs.org/). This plugin is available in the [npm repository](https://www.npmjs.org/package/leaflet.locatecontrol). Just run `npm install leaflet.locatecontrol`.\n\nThe control is [available from JsDelivr CDN](https://www.jsdelivr.com/projects/leaflet.locatecontrol). If you don't need the latest version, you can use the [mapbox CDN](https://www.mapbox.com/mapbox.js/plugins/#leaflet-locatecontrol).\n\n#### Add the JavaScript and CSS files\n\nThen include the CSS and JavaScript files.\n\n##### With CDN\n\nIn this example, we are loading the [files from the JsDelivr CDN](https://www.jsdelivr.com/package/npm/leaflet.locatecontrol?path=dist). In the URLs below, replace `[VERSION]` with the latest release number or remove `@[VERSION]` to always use the latest version.\n\n```html\n\u003clink rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/leaflet.locatecontrol@[VERSION]/dist/L.Control.Locate.min.css\" /\u003e\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/leaflet.locatecontrol@[VERSION]/dist/L.Control.Locate.min.js\" charset=\"utf-8\"\u003e\u003c/script\u003e\n```\n\n##### With `npm`\n\n```ts\nimport \"leaflet.locatecontrol\"; // Import plugin\nimport \"leaflet.locatecontrol/dist/L.Control.Locate.min.css\"; // Import styles\nimport L from \"leaflet\"; // Import L from leaflet to start using the plugin\n```\n\nIf you are using a bundler or esm, use\n\n```ts\nimport { LocateControl } from \"leaflet.locatecontrol\";\nimport \"leaflet.locatecontrol/dist/L.Control.Locate.min.css\";\n```\n\nThen use `new LocateControl()` instead of `L.control.locate()`.\n\n#### Add the following snippet to your map initialization:\n\nThis snippet adds the control to the map. You can pass also pass a configuration.\n\n```js\nL.control.locate().addTo(map);\n```\n\n### Possible options\n\nThe locate controls inherits options from [Leaflet Controls](http://leafletjs.com/reference.html#control-options).\n\nTo customize the control, pass an object with your custom options to the locate control.\n\n```js\nL.control.locate(OPTIONS).addTo(map);\n```\n\nPossible options are listed in the following table. More details are [in the code](https://github.com/domoritz/leaflet-locatecontrol/blob/gh-pages/src/L.Control.Locate.js#L118).\n\n\u003c!-- prettier-ignore-start --\u003e\n| Option     | Type      | Description       |  Default |\n|------------|-----------|-------------------|----------|\n| `position` | `string`  | Position of the control | `topleft` |\n| `layer` | [`ILayer`](http://leafletjs.com/reference.html#ilayer)  | The layer that the user's location should be drawn on. | a new layer |\n| `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'` |\n| `flyTo` | `boolean` | Smooth pan and zoom to the location of the marker. Only works in Leaflet 1.0+. | `false` |\n| `keepCurrentZoomLevel` | `boolean`  | Only pan when setting the view. | `false` |\n| `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` |\n| `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'}` |\n| `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` |\n| `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` |\n| `showCompass` | `boolean` | Show the compass bearing on top of the location marker | `true` |\n| `drawCircle` | `boolean`  | If set, a circle that shows the location accuracy is drawn. | `true` |\n| `drawMarker` | `boolean`  | If set, the marker at the users' location is drawn. | `true` |\n| `markerClass` | `class`  | The class to be used to create the marker. | `LocationMarker` |\n| `compassClass` | `class`  | The class to be used to create the marker. | `CompassMarker` |\n| `circleStyle` | [`Path options`](http://leafletjs.com/reference.html#path-options) | Accuracy circle style properties. | see code |\n| `markerStyle` | [`Path options`](http://leafletjs.com/reference.html#path-options) | Inner marker style properties. Only works if your marker class supports `setStyle`. | see code |\n| `compassStyle` | [`Path options`](http://leafletjs.com/reference.html#path-options) | Triangle compass heading marker style properties. Only works if your marker class supports `setStyle`. | see code |\n| `followCircleStyle` | [`Path options`](http://leafletjs.com/reference.html#path-options)  | Changes to the accuracy circle while following. Only need to provide changes. | `{}` |\n| `followMarkerStyle` | [`Path options`](http://leafletjs.com/reference.html#path-options)  | Changes to the inner marker while following. Only need to provide changes. | `{}` |\n| `followCompassStyle` | [`Path options`](http://leafletjs.com/reference.html#path-options)  | Changes to the compass marker while following. Only need to provide changes. | `{}` |\n| `icon` | `string`  | The CSS class for the icon. | `leaflet-control-locate-location-arrow` |\n| `iconLoading` | `string`  | The CSS class for the icon while loading. | `leaflet-control-locate-spinner` |\n| `iconElementTag` | `string`  | The element to be created for icons. | `span` |\n| `circlePadding` | `array`  | Padding around the accuracy circle. | `[0, 0]` |\n| `createButtonCallback` | `function`  | This callback can be used in case you would like to override button creation behavior. | see code |\n| `getLocationBounds` | `function`  | This callback can be used to override the viewport tracking behavior. | see code |\n| `onLocationError` | `function`  | This even is called when the user's location is outside the bounds set on the map. | see code |\n| `metric` | `boolean` | Use metric units. | `true` |\n| `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 |\n| `showPopup` | `boolean`  | Display a pop-up when the user click on the inner marker. | `true` |\n| `strings` | `object`  | Strings used in the control. Options are `title`, `text`, `metersUnit`, `feetUnit`, `popup` and `outsideMapBoundsMsg` | see code |\n| `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 |\n| `locateOptions` | [`Locate options`](http://leafletjs.com/reference.html#map-locate-options)  | The default options passed to leaflets locate method. | see code |\n\u003c!-- prettier-ignore-end --\u003e\n\nFor example, to customize the position and the title, you could write\n\n```js\nvar lc = L.control\n  .locate({\n    position: \"topright\",\n    strings: {\n      title: \"Show me where I am, yo!\"\n    }\n  })\n  .addTo(map);\n```\n\n## Screenshot\n\n![screenshot](https://raw.github.com/domoritz/leaflet-locatecontrol/gh-pages/screenshot.png \"Screenshot showing the locate control\")\n\n## Users\n\nSites that use this locate control:\n\n- [OpenStreetMap](http://www.openstreetmap.org/) on the start page\n- [MapBox](https://www.mapbox.com/mapbox.js/example/v1.0.0/leaflet-locatecontrol/)\n- [wheelmap.org](http://wheelmap.org/map)\n- [OpenMensa](http://openmensa.org/)\n- [Maps Marker Pro](https://www.mapsmarker.com) (WordPress plugin)\n- [Bikemap](https://jackdougherty.github.io/bikemapcode/)\n- [MyRoutes](https://myroutes.io/)\n- [NearbyWiki](https://en.nearbywiki.org/)\n- ...\n\n## Advanced Usage\n\n### Methods\n\nYou can call `start()` or `stop()` on the locate control object to set the location on page load for example.\n\n```js\n// create control and add to map\nvar lc = L.control.locate().addTo(map);\n\n// request location update and set location\nlc.start();\n```\n\nYou can keep the plugin active but stop following using `lc.stopFollowing()`.\n\n### Events\n\nYou 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](http://leafletjs.com/examples/mobile.html#geolocation).\n\nAdditionally, the locate control fires `locateactivate` and `locatedeactivate` events on the map object when it is activated and deactivated, respectively.\n\n### Extending\n\nTo 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.\n\n```js\nL.Control.MyLocate = L.Control.Locate.extend({\n  _drawMarker: function () {\n    // override to customize the marker\n  }\n});\n\nvar lc = new L.Control.MyLocate();\n```\n\n### FAQ\n\n#### How do I set the maximum zoom level?\n\nSet the `maxZoom` in `locateOptions` (`keepCurrentZoomLevel` must not be set to true).\n\n```js\nmap.addControl(\n  L.control.locate({\n    locateOptions: {\n      maxZoom: 10\n    }\n  })\n);\n```\n\n#### How do I enable high accuracy?\n\nTo enable [high accuracy (GPS) mode](http://leafletjs.com/reference.html#map-enablehighaccuracy), set the `enableHighAccuracy` in `locateOptions`.\n\n```js\nmap.addControl(\n  L.control.locate({\n    locateOptions: {\n      enableHighAccuracy: true\n    }\n  })\n);\n```\n\n#### Safari does not work with Leaflet 1.7.1\n\nThis is a bug in Leaflet. Disable tap to fix it for now. See [this issue](https://github.com/Leaflet/Leaflet/issues/7255) for details.\n\n```js\nlet map = new L.Map('map', {\n    tap: false,\n    ...\n});\n```\n\n## Developers\n\nRun the demo locally with `yarn start` or `npm run start` and then open [localhost:9000/demo/index.html](http://localhost:9000/demo/index.html).\n\nTo generate the minified JS and CSS files, use [grunt](http://gruntjs.com/getting-started) 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`.\n\n## Prettify and linting\n\nBefore a Pull Request please check the code style.\n\nRun `npm run lint` to check if there are code style or linting issues.\n\nRun `npm run:fix` to automatically fix style and linting issues.\n\n## Making a release (only core developer)\n\nA new version is released with `npm run bump:minor`. Then push the new code with `git push \u0026\u0026 git push --tags` and publish to npm with `npm publish`.\n\n### Terms\n\n- **active**: After we called `map.locate()` and before `map.stopLocate()`. Any time, the map can fire the `locationfound` or `locationerror` events.\n- **following**: Following refers to whether the map zooms and pans automatically when a new location is found.\n\n## Thanks\n\nTo all [contributors](https://github.com/domoritz/leaflet-locatecontrol/contributors) and issue reporters.\n\n## License\n\nMIT\n\nSVG icons from [Font Awesome v5.15.4](https://github.com/FortAwesome/Font-Awesome/releases/tag/5.15.4): [Creative Commons Attribution 4.0](https://fontawesome.com/license/free)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdomoritz%2Fleaflet-locatecontrol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdomoritz%2Fleaflet-locatecontrol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdomoritz%2Fleaflet-locatecontrol/lists"}