Vector tiles for the web with Leaflet¶
Free
Starter
Standard
Professional
Leaflet is a well-known, mature JavaScript mapping library with an active community and a variety of plugins, giving you plenty of room to grow. Most users will find that Leaflet works well for their use cases and has the added bonus of being super lightweight with a simple API.
While Leaflet does not natively support vector tile rendering, the maplibre-gl-leaflet plugin works quite well in most cases. You can keep using the familiar (and powerful) Leaflet APIs and get most of the benefits of vector tiles, including the ability to use a custom style. This tutorial will show you how!
Code¶
Let's dive in with some example code on how to use our vector tiles in Leaflet.
If you are implementing the code locally, nothing special is required. If you are developing outside of localhost,
only a free account is required. You can learn more about our accounts and authentication here.
You can play around immediately with the example code by clicking on the Try it in JSFiddle link. A new tab will open,
allowing you to interact with the map and make adjustments to the code.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
<title>Vector Map Demo (Leaflet)</title>
<!-- Leaflet -->
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
<script type="text/javascript" src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
<!-- MapLibre GL JS (still required to handle the rendering) -->
<script type="text/javascript" src="//unpkg.com/maplibre-gl@4.0.2/dist/maplibre-gl.js"></script>
<link href="//unpkg.com/maplibre-gl@4.0.2/dist/maplibre-gl.css" rel="stylesheet" />
<!-- Mapbox GL Leaflet -->
<script src="https://unpkg.com/@maplibre/maplibre-gl-leaflet@0.0.20/leaflet-maplibre-gl.js"></script>
<style type="text/css">
html, body, #map {
width: 100%;
height: 100%;
margin: 0;
}
</style>
</head>
<body>
<div id="map"></div>
<script type="text/javascript">
// Initialize a map centered at (53, 12) at zoom level 5
var map = L.map('map').setView([53, 12], 5);
// MapLibre GL JS does not handle RTL text by default,
// so we recommend adding this dependency to fully support RTL rendering if your style includes RTL text
maplibregl.setRTLTextPlugin('https://unpkg.com/@mapbox/mapbox-gl-rtl-text@0.2.3/mapbox-gl-rtl-text.min.js');
L.maplibreGL({
style: 'https://tiles.stadiamaps.com/styles/alidade_smooth_dark.json', // Style URL; see our documentation for more options
attribution: '© <a href="https://stadiamaps.com/" target="_blank">Stadia Maps</a>, © <a href="https://openmaptiles.org/" target="_blank">OpenMapTiles</a> © <a href="https://www.openstreetmap.org/copyright" target="_blank">OpenStreetMap</a>',
}).addTo(map);
</script>
</body>
</html>
Code walkthrough¶
First, we'll add some opening HTML content that will make the document standard compliant:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
<title>Vector Map Demo (Leaflet)</title>
Next, we'll include the Leaflet library files:
<!-- Leaflet -->
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
<script type="text/javascript" src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
Along with the MapLibre library files, including the maplibre-gl-leaflet plugin:
<!-- MapLibre GL JS (still required to handle the rendering) -->
<script type="text/javascript" src="//unpkg.com/maplibre-gl@4.0.2/dist/maplibre-gl.js"></script>
<link href="//unpkg.com/maplibre-gl@4.0.2/dist/maplibre-gl.css" rel="stylesheet" />
<!-- Mapbox GL Leaflet -->
<script src="https://unpkg.com/@maplibre/maplibre-gl-leaflet@0.0.20/leaflet-maplibre-gl.js"></script>
Now, we'll add CSS to handle the size of the body, the map ID, and then close the <head> tag:
<style type="text/css">
html, body, #map {
width: 100%;
height: 100%;
margin: 0;
}
</style>
</head>
With the <head> details in, we can now add the body for our page. This is where we'll create the map element:
<body>
<div id="map"></div>
Next, we'll add the JavaScript for:
- initializing the map, including its center point and zoom level:
<script type="text/javascript">
// Initialize a map centered at (53, 12) at zoom level 5
var map = L.map('map').setView([53, 12], 5);
- adding the RTL text dependency:
// MapLibre GL JS does not handle RTL text by default,
// so we recommend adding this dependency to fully support RTL rendering if your style includes RTL text
maplibregl.setRTLTextPlugin('https://unpkg.com/@mapbox/mapbox-gl-rtl-text@0.2.3/mapbox-gl-rtl-text.min.js');
- initializing a new map and styling it with Alidade Smooth Dark:
L.maplibreGL({
style: 'https://tiles.stadiamaps.com/styles/alidade_smooth_dark.json', // Style URL; see our documentation for more options
- and adding proper attribution, drawing it to the map element, and closing the
<script>tag:
attribution: '© <a href="https://stadiamaps.com/">Stadia Maps</a>, © <a href="https://openmaptiles.org/">OpenMapTiles</a> © <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a>',
}).addTo(map);
</script>
Finally, we'll close up the <body>, and <html> tags:
</body>
</html>
And that's it. Congratulations!
All the code, put together, will match the code at the start of this tutorial. Now you can play around with the starting point, zoom level, and styles to customize the map to your liking.
Next Steps¶
This tutorial doesn't even begin to show what's possible with Leaflet. Now that you have a map, you can get inspiration from what others have built at the Leaflet Examples page. They have in-depth examples covering everything from custom markers to interactive choropleth maps. And don't forget to check out the plugins and the rest of the Leaflet documentation either.
Once you're ready to move beyond localhost testing, sign up for a free Stadia Maps account,
and we'll walk through the next steps.