PHPackages                             sylvainjule/locator - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. sylvainjule/locator

ActiveKirby-plugin[Utility & Helpers](/categories/utility)

sylvainjule/locator
===================

A map & geolocation field, built on top of open-source services / Mapbox

2.1.0(9mo ago)11237.3k—5.4%16[1 issues](https://github.com/sylvainjule/kirby-locator/issues)[1 PRs](https://github.com/sylvainjule/kirby-locator/pulls)1MITVue

Since Dec 26Pushed 9mo ago4 watchersCompare

[ Source](https://github.com/sylvainjule/kirby-locator)[ Packagist](https://packagist.org/packages/sylvainjule/locator)[ Fund](https://www.paypal.me/sylvainjl)[ GitHub Sponsors](https://github.com/sylvainjule)[ RSS](/packages/sylvainjule-locator/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (1)Versions (18)Used By (1)

Kirby Locator
=============

[](#kirby-locator)

A simple map & geolocation field, built on top of open-source services and Mapbox.

[![screenshot](https://private-user-images.githubusercontent.com/14079751/475266122-c6c24f87-38fe-4a57-8ee7-444ae0f899e7.jpg?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzUzMzMxMzMsIm5iZiI6MTc3NTMzMjgzMywicGF0aCI6Ii8xNDA3OTc1MS80NzUyNjYxMjItYzZjMjRmODctMzhmZS00YTU3LThlZTctNDQ0YWUwZjg5OWU3LmpwZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjA0MDQlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwNDA0VDIwMDAzM1omWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPWZiMWE3YjgxOTZjMjJhYTFkMmUzZjNmZTgzNjRlNzgwNWJhYzllMGUyYzFmMTc1MWMzMzkxYWU4MTU1NDU2YTkmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.dThIeYnjsth7l7QuBckG3ZI1G2NhPpEgHY0tyYnexVU)](https://private-user-images.githubusercontent.com/14079751/475266122-c6c24f87-38fe-4a57-8ee7-444ae0f899e7.jpg?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzUzMzMxMzMsIm5iZiI6MTc3NTMzMjgzMywicGF0aCI6Ii8xNDA3OTc1MS80NzUyNjYxMjItYzZjMjRmODctMzhmZS00YTU3LThlZTctNDQ0YWUwZjg5OWU3LmpwZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjA0MDQlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwNDA0VDIwMDAzM1omWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPWZiMWE3YjgxOTZjMjJhYTFkMmUzZjNmZTgzNjRlNzgwNWJhYzllMGUyYzFmMTc1MWMzMzkxYWU4MTU1NDU2YTkmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.dThIeYnjsth7l7QuBckG3ZI1G2NhPpEgHY0tyYnexVU)

Overview
--------

[](#overview)

> This plugin is completely free and published under the MIT license. However, if you are using it in a commercial project and want to help me keep up with maintenance, you can consider [making a donation of your choice](https://www.paypal.me/sylvainjl).

- [1. Installation](#1-installation)
- [2. Setup](#2-setup)
- [3. Tile-servers](#3-tile-servers)
    - [3.1. Open-source / free tiles](#31-open-source-free-tiles)
    - [3.2. Mapbox tiles](#32-mapbox-tiles)
- [4. Geocoding service](#4-geocoding-service)
    - [4.1. Open-source API (Nominatim)](#41-open-source-nominatim)
    - [4.2. Mapbox API](#42-mapbox-api)
- [5. Per-field options](#5-per-field-options)
- [6. Global options](#6-global-options)
- [7. Front-end usage](#6-front-end-usage)
- [8. Credits](#7-credits)
- [9. License](#8-license)

1. Installation
---------------

[](#1-installation)

> Kirby 3: up to 1.1.4. Kirby 4: 2.0.0+

Download and copy this repository to `/site/plugins/locator`

Alternatively, you can install it with composer: `composer require sylvainjule/locator`

2. Setup
--------

[](#2-setup)

Out of the box, the field is set to use open-source services both for geocoding (Nominatim) and tiles-rendering (Positron), without any API-key requirements.

Keep in mind that **these services are bound by strict usage policies**, always double-check if your usage is compatible. Otherwise, please set-up the field to use Mapbox, see details below.

You can also directly enter latitude / longitude coordinates and bypass the geolocation (in a format such as: `15.23456, -30.67890`).

```
mymap:
  label: Location
  type: locator
```

3. Tile-servers
---------------

[](#3-tile-servers)

#### 3.1. Open-source / free tiles

[](#31-open-source--free-tiles)

[![tiles-opensource-2](https://user-images.githubusercontent.com/14079751/48648038-2c542380-e9ee-11e8-8668-4170ef107195.jpg)](https://user-images.githubusercontent.com/14079751/48648038-2c542380-e9ee-11e8-8668-4170ef107195.jpg)

You can pick one of the 4 free tile servers included:

1. `wikimedia` ([Terms of Use](https://foundation.wikimedia.org/wiki/Maps_Terms_of_Use)) → Public usage is now forbidden
2. `openstreetmap` ([Terms of Use](https://wiki.openstreetmap.org/wiki/Tile_usage_policy))
3. `positron` (default, [Terms of Use](https://carto.com/legal/) \[Under *Free Basemaps Terms of Service*\])
4. `voyager` ([Terms of Use](https://carto.com/legal/) \[Under *Free Basemaps Terms of Service*\])

```
mymap:
  type: locator
  tiles: positron
```

You can also set this globally in your installation's main `config.php`, then you won't have to configure it in every blueprint:

```
return array(
    'sylvainjule.locator.tiles' => 'positron',
);
```

#### 3.2. Mapbox tiles

[](#32-mapbox-tiles)

[![tiles-mapbox-2](https://user-images.githubusercontent.com/14079751/48648037-2c542380-e9ee-11e8-916d-ca240a40bc20.jpg)](https://user-images.githubusercontent.com/14079751/48648037-2c542380-e9ee-11e8-916d-ca240a40bc20.jpg)

1. mapbox.outdoors → `mapbox/outdoors-v11` (default mapbox theme)
2. mapbox.streets → `mapbox/streets-v11`
3. mapbox.light → `mapbox/light-v10`
4. mapbox.dark → `mapbox/dark-v10`

In case your usage doesn't fall into the above policies (or if you don't want to rely on those services), you can set-up the field to use Mapbox' tiles.

You will have to set both the `id` of the tiles you want to use and your mapbox `public key` in your installation's main `config.php`:

```
return array(
    'sylvainjule.locator.mapbox.id'    => 'mapbox/outdoors-v11',
    'sylvainjule.locator.mapbox.token' => 'pk.vdf561vf8...',
);
```

You can now explicitely state in your blueprint that you want to use Mapbox tiles:

```
mymap:
  type: locator
  tiles: mapbox
```

You can also set this globally in your installation's main `config.php`, then you won't have to configure it in every blueprint:

```
return array(
    'sylvainjule.locator.tiles' => 'mapbox',
);
```

4. Geocoding services
---------------------

[](#4-geocoding-services)

#### 4.1. Open-source API (Nominatim)

[](#41-open-source-api-nominatim)

This is the default geocoding service. It doesn't require any additional configuration, but please double-check if your needs fit the [Nominatim Usage Policy](https://operations.osmfoundation.org/policies/nominatim/).

```
mymap:
  type: locator
  geocoding: nominatim
```

#### 4.2. Mapbox API

[](#42-mapbox-api)

In case your usage doesn't fall into the above policy (or if you don't want to use Nominatim), you can set-up the field to use Mapbox API.

If you haven't already, you will have to set your mapbox `public key` in your installation's main `config.php`:

```
return array(
    'sylvainjule.locator.mapbox.token' => 'pk.vdf561vf8...',
);
```

You can now explicitely state in your blueprint that you want to use Mapbox as a geocoding service:

```
mymap:
  type: locator
  geocoding: mapbox
```

You can also set this globally in your installation's main `config.php`, then you won't have to configure it in every blueprint:

```
return array(
    'sylvainjule.locator.geocoding' => 'mapbox',
);
```

5. Per-field options
--------------------

[](#5-per-field-options)

#### 5.1. `center`

[](#51-center)

The coordinates of the center of the map, if the field has no stored value. Default is `{lat: 48.864716, lon: 2.349014}` (Paris, FR).

```
mymap:
  type: locator
  center:
    lat: 48.864716
    lon: 2.349014
```

#### 5.2. `zoom`

[](#52-zoom)

The `min`, `default` and `max` zoom values, where `default` will be the one used on every first-load of the map. Default is: `{min: 2, default: 12, max: 18}`.

```
mymap:
  type: locator
  zoom:
    min: 2
    default: 12
    max: 18
```

#### 5.3. `saveZoom`

[](#53-savezoom)

Whether the field should store the zoom level of the map when the marker was added, and use it as default zoom value afterwards. Default is `false`.

```
mymap:
  type: locator
  saveZoom: false
```

#### 5.4. `autoSaveZoom`

[](#54-autosavezoom)

Whether the field should store the zoom level of the map when the user changes the zoom manually, and use it as default zoom value afterwards. Default is `false`.

```
mymap:
  type: locator
  autoSaveZoom: false
```

#### 5.5. `display`

[](#55-display)

The informations to be displayed in the panel. Note that it will only hide them from the panel view, they will still be stored (if available) in the .txt file. To be picked from `lat`, `lon`, `number`, `address`, `postcode`, `city`, `region`, `country` and `countryCode`. Default includes them all but `countryCode`.

If you are using Nominatim, the field also stores the OpenStreetMap ID under the `osm` key, which you can also display by adding it to the list.

If you don't want any information to show up, set it to `false`.

```
mymap:
  type: locator
  display:
    - lat
    - lon
    - number
    - address
    - postcode
    - city
    - region
    - country
    - countryCode
```

#### 5.6. `draggable`

[](#56-draggable)

If set to `true`, the marker will be repositionable in case search result isn't precise enough. After being moved, only the new `lat` and `lng` will be stored. Default is `true`.

#### 5.7. `collapse`

[](#57-collapse)

If set to `true`, the map will collapse when a location is selected, with a toggle to expand it for editing. If `false`, the map will always be expanded and interactive. Default is `true`.

#### 5.8. `autocomplete`

[](#58-autocomplete)

If set to `true`, **when Mapbox is used for geocoding**, you will be presented up to 5 suggestions while typing your request. Default is `true`.

#### 5.9. `liststyle`

[](#59-liststyle)

[![liststyle](https://user-images.githubusercontent.com/14079751/48487819-9cf91580-e81f-11e8-8e20-eba57f122261.jpg)](https://user-images.githubusercontent.com/14079751/48487819-9cf91580-e81f-11e8-8e20-eba57f122261.jpg)

The style of the informations block, either `columns` or `table`. Default is `table`.

```
mymap:
  type: locator
  liststyle: table
```

#### 5.10. `marker`

[](#510-marker)

The color of the marker used, either `dark`, `light` or your own HEX value. Default is `dark`.

```
mymap:
  type: locator
  marker: dark
```

#### 5.11. `language`

[](#511-language)

If this option is set with an [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (en, fr, de, etc.), the geocoding service will return results in the requested language if available. Default is `false`.

```
mymap:
  type: locator
  language: false # or 'de' | 'fr' | 'en' | …
```

#### 5.12. `dblclick`

[](#512-dblclick)

Whether a double click on the map should trigger a zoom (`zoom`) or add a marker / move the existing marker to the coordinates of the click event (`marker`). Default is `zoom`.

```
mymap:
  type: locator
  dblclick: zoom # or 'marker'
```

6. Global options
-----------------

[](#6-global-options)

The same options are available globally, which means you can set them all in your installation's `config.php` file and don't worry about setting it up individually afterwards:

```
return array(
    'sylvainjule.locator.center.lat'   => 48.864716,
    'sylvainjule.locator.center.lon'   => 2.349014,
    'sylvainjule.locator.zoom.min'     => 2,
    'sylvainjule.locator.zoom.default' => 12,
    'sylvainjule.locator.zoom.max'     => 18,
    'sylvainjule.locator.saveZoom'     => false,
    'sylvainjule.locator.autoSaveZoom' => false,
    'sylvainjule.locator.display'      => array('lat','lon','number','address','postcode','city','country'),
    'sylvainjule.locator.draggable'    => true,
    'sylvainjule.locator.collapse'     => true,
    'sylvainjule.locator.autocomplete' => true,
    'sylvainjule.locator.liststyle'    => 'columns',
    'sylvainjule.locator.marker'       => 'dark',
    'sylvainjule.locator.language'     => false,
    'sylvainjule.locator.dblclick'     => 'zoom',
);
```

7. Front-end usage
------------------

[](#7-front-end-usage)

The location data is stored as YAML and therefore needs to be decoded with the `yaml` method or using the `toLocation` method (see below):

```
$location = $page->mymap()->yaml();
```

Potential stored keys are:

- `lat` (Latitude)
- `lon` (Longitude)
- `number` (Street number)
- `address` (Street / road / place)
- `city` (city / village)
- `region` (region / state)
- `country` (country)
- `countryCode` (country code)
- `osm` (OpenStreetMap ID, if using Nominatim)

It is possible that the found location doesn't have one of those keys, which will therefore not be saved. It is important to always check if the key exists, and if it's not empty. Here's one way to do it:

```
$location = $page->mymap()->yaml();

if(!empty($location['postcode'])) {
    // there is a filled 'postcode' key
}
else {
    // there is no / an empty 'postcode' key
}
```

Alternatively, you can use the `toLocation` method to convert the value to a new collection, an use it kirby-style:

```
$location = $page->mymap()->toLocation();

// You now have access to
// $location->lat()
// $location->lon()
// ...

if($location->has('postcode')) {
    if($location->postcode()->isNotEmpty()) {
        // there is a filled 'postcode' key
    }
    else {
        // there is an empty 'postcode' key
    }
}
else {
  // there is no 'postcode' key
}
```

8. Credits
----------

[](#8-credits)

**Services:**

- [Openstreetmap](https://www.openstreetmap.org/#map=5/46.449/2.210), [Wikimedia](https://maps.wikimedia.org), [Carto](https://carto.com/) or [Mapbox](https://www.mapbox.com/) as tile servers.
- [Nominatim](https://nominatim.openstreetmap.org/) or [Mapbox Search](https://www.mapbox.com/search/) as a geocoding API
- [Leaflet](https://leafletjs.com/) as a mapping library.

**K2 fields:**

- [Map-field](https://github.com/AugustMiller/kirby-map-field) by [@AugustMiller](https://github.com/AugustMiller)
- Its [open-source fork](https://github.com/fendinger/kirby-osmap-field) by [@fendinger](https://github.com/fendinger)

9. License
----------

[](#9-license)

MIT

###  Health Score

52

—

FairBetter than 96% of packages

Maintenance57

Moderate activity, may be stable

Popularity45

Moderate usage in the ecosystem

Community22

Small or concentrated contributor base

Maturity69

Established project with proven stability

 Bus Factor1

Top contributor holds 90.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~150 days

Recently: every ~313 days

Total

17

Last Release

287d ago

Major Versions

1.1.4 → 2.0.02024-03-08

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/14079751?v=4)[Sylvain Julé](/maintainers/sylvainjule)[@sylvainjule](https://github.com/sylvainjule)

---

Top Contributors

[![sylvainjule](https://avatars.githubusercontent.com/u/14079751?v=4)](https://github.com/sylvainjule "sylvainjule (90 commits)")[![afbora](https://avatars.githubusercontent.com/u/3393422?v=4)](https://github.com/afbora "afbora (2 commits)")[![PiotrF](https://avatars.githubusercontent.com/u/111983916?v=4)](https://github.com/PiotrF "PiotrF (2 commits)")[![S1SYPHOS](https://avatars.githubusercontent.com/u/12161504?v=4)](https://github.com/S1SYPHOS "S1SYPHOS (2 commits)")[![sebastiangreger](https://avatars.githubusercontent.com/u/6355217?v=4)](https://github.com/sebastiangreger "sebastiangreger (2 commits)")[![medienbaecker](https://avatars.githubusercontent.com/u/7975568?v=4)](https://github.com/medienbaecker "medienbaecker (1 commits)")

---

Tags

coordinatesgeocodinggeolocationkirbykirby-pluginleafletlocationmapmapbox

### Embed Badge

![Health badge](/badges/sylvainjule-locator/health.svg)

```
[![Health](https://phpackages.com/badges/sylvainjule-locator/health.svg)](https://phpackages.com/packages/sylvainjule-locator)
```

###  Alternatives

[distantnative/retour-for-kirby

Manage redirects and track 404s right from the Kirby CMS Panel

14689.4k1](/packages/distantnative-retour-for-kirby)[mzur/kirby-uniform

A versatile Kirby plugin to handle web form actions.

26068.3k13](/packages/mzur-kirby-uniform)[arnoson/kirby-vite

Vite helper for Kirby CMS

9759.2k3](/packages/arnoson-kirby-vite)[thathoff/kirby-git-content

Plugin to track changes to content in a git repository.

15343.7k](/packages/thathoff-kirby-git-content)[tobimori/kirby-seo

The default choice for SEO on Kirby: Implement technical SEO & Meta best practices with ease and provide an easy-to-use editor experience

10039.7k1](/packages/tobimori-kirby-seo)[fabianmichael/kirby-meta

Your all-in-one powerhouse for any SEO and metadata needs imaginable.

6910.7k1](/packages/fabianmichael-kirby-meta)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)