Creating raster maps with Leaflet¶

Free

Starter

Standard

Professional

Displaying a grid of image tiles is the traditional way of displaying electronic maps. Due to their nature, raster tiles are limited in functionality, such as the ability to create 3D effects or change styling on the fly, but some use cases or libraries require them.

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.

What if I have a more advanced use case?

We recommend using Leaflet for your raster maps unless you know you need something more advanced. For more complex geospatial applications, we typically recommend OpenLayers.

In this tutorial you'll learn how to build a simple raster map using Leaflet. We'll keep things simple and operate in the context of a simple web page.

Using a framework like React or Vue?

If you're using a framework, check out our quickstart tutorials specific to what you're using. We have tutorials for React and Vue.

Code¶

Let's dive in with some example code on how to use our raster 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>Raster Map Demo (Leaflet)</title>
        <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>
        <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);

            // Style URL format in XYZ PNG format; see our documentation for more options
            L.tileLayer('https://tiles.stadiamaps.com/tiles/alidade_smooth/{z}/{x}/{y}{r}.png', {
                maxZoom: 20,
                attribution: '&copy; <a href="https://stadiamaps.com/" target="_blank">Stadia Maps</a>, &copy; <a href="https://openmaptiles.org/" target="_blank">OpenMapTiles</a> &copy; <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 lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
        <title>Raster Map Demo (Leaflet)</title>

Next, we'll include the Leaflet libraries:

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

Now, we'll add some CSS to handle the size of the map class 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);

styling it with Alidade Smooth raster tiles:

          // Style URL format in XYZ PNG format; see our map style library for more options: https://docs.stadiamaps.com/themes/
          // Be sure to include the `{r}` placeholder as shown below to support retina screens.
          L.tileLayer('https://tiles.stadiamaps.com/tiles/alidade_smooth/{z}/{x}/{y}{r}.png', {
              maxZoom: 20,

and adding proper attribution, drawing it to the map element, and closing the <script> tag:

                   attribution: '&copy; <a href="https://stadiamaps.com/" target="_blank">Stadia Maps</a>, &copy; <a href="https://openmaptiles.org/" target="_blank">OpenMapTiles</a> &copy; <a href="https://www.openstreetmap.org/copyright" target="_blank">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.

Get Started With a Free Account