Skip to content

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.

For local development on a web server at localhost or 127.0.0.1, you can get started without any special setup! For mobile, server, and non-local web development, sign up for a free account to configure domain auth or an API key. Our authentication guide has all the gritty details.

To make experimenting even easier, we've packaged the example code as a JSFiddle playground. Click the "Try it in JSFiddle" button to start experimenting right from your web browser.

Try it in JSFiddle
<!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);
          // 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