This is a binding from [MapTiler SDK JS/TS](https://docs.maptiler.com/sdk-js/) to the familiar
-[Leaflet](http://leafletjs.com/) API. This is a fork of the [MapLibre version](https://github.com/maplibre/maplibre-gl-leaflet).
+[Leaflet](http://leafletjs.com/) API.
**MapTiler SDK JS** is an extension of MapLibre GL JS, fully backward compatible, tailored for MapTiler Cloud and with plenty of extra features!
-## Code example
-```javascript
+
-const map = L.map('map').setView([38.912753, -77.032194], 15);
-L.marker([38.912753, -77.032194])
- .bindPopup("Hello Leaflet GL! Whoa, it works!")
- .addTo(map)
- .openPopup();
+## Usage
+### From ES module using `import`
+For the following examples, we are using the [Vite vanilla JS app](https://vitejs.dev/guide/) as a starting point.
-const mtLayer = L.maptilerLayer({
- style: "https://api.maptiler.com/maps/streets-v2/style.json?key=YOUR_MAPTILER_API_KEY",
-}).addTo(map);
+The typical Leaflet plugin usualy adds new elements directly in the global object `L` and even though this API design is now a bit dated and somewhat frown uppon, we did not want to disrupt the dev experiece for those used to this. For this reason, you will need to import the plugin but not a specific object from it, as `MaptilerLayer` is internally added to `L`:
+
+```js
+// import Leaflet and its style
+import L from "leaflet";
+import "leaflet/dist/leaflet.css";
+
+// Import the Leaflet MapTiler Plugin
+import "@maptiler/leaflet-maptilersdk";
+
+// Import your custom style,
+// depending on your configuration, you may have to change how this is done
+import './style.css';
```
-You can also use any of the MapTiler style shorthand alongside the `apiKey` option:
-```javascript
-const mtLayer = L.maptilerLayer({
+Then, in the Vite vanilla app, we would have to do exactely like in regular vanilla JS:
+```js
+// Center the map on Manhattan, zoom level 13
+const map = L.map("map").setView([40.7468, -73.98775], 13);
+
+// Center the map on Manhattan, zoom level 13
+L.marker([40.7468, -73.98775])
+ .bindPopup("Hello Leaflet with MapTiler SDK")
+ .addTo(map)
+ .openPopup();
+
+// Create a MapTiler Layer inside Leaflet
+const mtLayer = new L.MaptilerLayer({
+ // Get your free API key at https://cloud.maptiler.com
apiKey: "YOUR_MAPTILER_API_KEY",
- style: L.MaptilerStyle.STREETS, // optional
}).addTo(map);
```
-Get an API key with the generous free plan at [cloud.maptiler.com](https://cloud.maptiler.com/)
+If you would rather stick to more modern API design and do not feel like using the `L` object, we got you covered:
+
+```js
+import { MaptilerLayer } from "@maptiler/leaflet-maptilersdk";
+
+// ...
+
+const mtLayer = new MaptilerLayer( options );
+```
+
+## From ES module, the *async* way
+Some frontend frameworks always are very opinionated regarding Server-Side-rendering and will attemp to perform it, that's the case of [Next.js](https://nextjs.org/). But Leaflet does not play well with it because there are some direct calls to the global `window` object, and this would crash on a server. The fix consists in importing Leaflet dynamically, and then `@maptiler/leaflet-maptilersdk` can also be imported.
+
+The React lifecycle method `.componentDidMount()` of a class component is only called on the frontend so this is why we have decided to dynamically import from there, but feel free to adapt your code if you are using a function component or a non-React app:
+
+```js
+componentDidMount() {
+ // assuming this was init with React.createRef()
+ const container = this.mapContainer.current;
+
+ // A self-callable async function because importing packages dynamically is an async thing to do
+ (async () => {
-Once you have created the leaflet layer, the MapTiler SDK `Map` instance can be accessed using
-```javascript
-const maptilerMap = mtLayer.getMaptilerMap();
+ // dynamic import of Leaflet
+ const L = await import('leaflet');
-// add a source to the MapTiler SDK layer, just like you would do with the MapTiler SDK
-mtLayer.getMaptilerMap().addSource({...});
+ // dynamic import of the library
+ const leafletmaptilersdk = await import('@maptiler/leaflet-maptilersdk');
+
+ // Creating the Leaflet map
+ const map = L.map(container).setView([51.505, -0.09], 10);
+
+ // Creating the MapTiler Layer
+ const mtLayer = new leafletmaptilersdk.MaptilerLayer({
+ apiKey: "YOUR_API_KEY",
+ }).addTo(map);
+
+ })()
+}
```
-## Examples
-The [examples](examples) folder of this repository is a good place to start!
-## Installation
-Add a script tag referencing leaflet-maptilersdk after adding leaflet and MapTiler SDK in your website:
+### From CDN with the UMD bundle
+The UDM *leaflet-maptilersdk* bundle is not package with Leaflet nor with MapTiler SDK, so those will have to be imported as `
-
-
+
+
```
-## Motivation
-This project makes it possible to easily add a MapTiler SDK JS layer in your Leaflet map. When using leaflet-maptilersdk, you won't be able to use some of the MapTiler SDK features.
-Here are the main differences between a "pure" MapTiler SDK map and a Leaflet map using maptilesdk-leaflet:
-- No rotation / bearing / pitch support
-- Slower performances: When using leaflet-maptilersdk, MapTiler SDK is set as not interactive. Leaflet receives the touch/mouse events and updates the MapTiler SDK map behind the scenes. Because MapTiler SDK doesn't redraw as fast as Leaflet, the map can seem slower.
-- Terrain elevation is possible but will create a parallax effect that will result in a missalignment of other Leaflet features (markers, overlays, etc.)
+Then, in the HTML ``, decalre the container that will host the map:
+```html
+
+```
-On the bright side, the leaflet-maptilersdk binding will allow you to use all the leaflet features and plugins.
+Finally, add a `
@@ -20,29 +22,34 @@
+
+
+
-
+
+ official page →