Raster maps for web

Displaying a grid of image tiles to make up a map is the traditional way of doing electronic maps. These consume more bandwidth and will be slower to load as a result, but some applications work only with raster tiles. If you are able to use vector, we encourage you to do so, as they will always look better and usually load faster.

For raster maps, many JavaScript libraries exist. We recommend using either the well-known Leaflet or mapbox.js libraries for most applications. Mapbox.js is actually an extension of Leaflet. Which you use is a matter of preference, but the Mapbox.js setup is ever so slightly shorter.

For advanced users, we recommend OpenLayers. While it is a little heavier and has a steeper learning curve than the others, it's feature set is second to none.

Displaying a map (Leaflet)

Below is an example of how to use our tiles in Leaflet. Nothing special is required. Just point to the tile URL for the style you want and everything should work seamlessly as long as you have an active plan for your domain. Be sure to include the {r} placeholder as shown below to support retina screens.

<!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</title>
        <link rel="stylesheet" href="https://unpkg.com/leaflet@1.3.1/dist/leaflet.css" />
        <script src="https://unpkg.com/leaflet@1.3.1/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>
            // Initialize a map centered at (50, 12) at zoom level 4
            var map = L.map('map').setView([12, 53], 4);

            // Theme URL format in XYZ PNG format; see our themes 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/">Stadia Maps</a>, &copy; <a href="https://openmaptiles.org/">OpenMapTiles</a> &copy; <a href="http://openstreetmap.org">OpenStreetMap</a> contributors',
            }).addTo(map);
        </script>
    </body>
</html>

Displaying a map (Mapbox.js)

The Mapbox.js example is quite similar. The key difference in the initialization process is that you can use a TileJSON URL rather than a format string. You also don't need to manually add attribution information, as this is derived from the TileJSON automatically.

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <title>Raster Map Demo</title>
        <script src="https://api.mapbox.com/mapbox.js/v3.1.1/mapbox.js"></script>
        <link rel="stylesheet" type="text/css" href="https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.css" />
        <style>
            body { margin:0; padding:0; }
            #map { position:absolute; top:0; bottom:0; width:100%; }
        </style>
    </head>
    <body>
        <div id='map'></div>
        <script>
            // Initialize a map, much as we did before.
            // This time we use a TileJSON URL though rather than having to set up our
            // first tile layer manually with a format string.
            var map = L.mapbox.map('map', 'https://tiles.stadiamaps.com/styles/alidade_smooth/rendered.json', { zoomControl: false });
            map.setView([53, 12], 5);
            new L.Control.Zoom({ position: 'topright' }).addTo(map);
        </script>
    </body>
</html>

Further reading

This certainly isn't all there is to know about Leaflet and Mapbox.js. Check out the official documentation for Leaflet and official documentation for Mapbox.js to learn about more advanced usage, including markers, overlays, and more.