How to Add XYZ Tile Layers to a Mapbox GL JS Map

This article teaches you how to create a simple Mapbox GL JS application with XYZ tile layers. You can use any of the layers on our categorized layer list to add to the application.

Here is a CodePen of the resulting application:

First, let's create an index.html file:

index.html

<!DOCTYPE html>
<html>
  <head>
    <title>MapBox GL JS - XYZ Tiles Demo</title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1, user-scalable=no" />
    <link rel="stylesheet" href="https://api.mapbox.com/mapbox-gl-js/v2.7.0/mapbox-gl.css" />
    <link rel="stylesheet" href="style.css" />
    <script src="https://api.mapbox.com/mapbox-gl-js/v2.7.0/mapbox-gl.js"></script>
  </head>
  <body>
    <div id="map"></div>
    <script src="main.js"></script>
  </body>
</html>

What's happening here:

We include Mapbox GL JS CSS file on line 7.
We include a CSS file on line 8 that we will create later.
We include Mapbox GL JS JavaScript file on line 9.
We create a container for the map on line 12, defining 'map' as the id (you can use any id you want).
We include a JavaScript file on line 13 that we will create later.

Now, let's create a style.css file to style the map:

style.css

html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}

#map {
  height: 100%;
}

These rules will make our map appear full screen.

Finally, we'll create a main.js file that will handle creating layers and adding them to the map:

main.js

mapboxgl.accessToken = 'YOUR_ACCESS_TOKEN';

const cartoDBDarkMatter = {
  type: 'raster',
  tiles: [
    'https://a.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png',
    'https://b.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png',
    'https://c.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png',
    'https://d.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png'
  ],
  tileSize: 256,
  attribution: '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors &copy; <a href="https://carto.com/attributions">CARTO</a>',
  minzoom: 0,
  maxzoom: 19
};

const map = new mapboxgl.Map({
  container: 'map',
  style: {
    version: 8,
    sources: {
      'xyz-tiles-source': cartoDBDarkMatter
    },
    layers: [
      {
        id: 'xyz-tiles',
        type: 'raster',
        source: 'xyz-tiles-source'
      }
    ]
  },
  center: [-1.5, 52.2],
  zoom: 7
});

Let's break it down:

We insert the mapboxgl.accessToken on line 1. You can get your access token by following Mapbox's instructions.
We define the tile layer source on lines 3-15 (the highlighted part) and save it to a variable.
Lastly, we initialize the map on lines 17-34:
- We use 'map' to refer to the map container that we added to the HTML file.
- We then define the map's style by specifying a version number, adding key-value pairs of sources (we use 'xyz-tiles-source' as the id, but you can use whatever you like), and layers as list of layer definition objects (each layer has to be set an id, source, and 'raster' type for XYZ tile layers - again, you can use any id you want here).
- Finally we set the map's view to our chosen geographical coordinates and zoom level (here we use coordinates for some place in England).

You can pick any of the layers from our categorized layer list to add to your application. Just copy the code to create the layer source in the preview application and paste it into your JavaScript file in place of the highlighted part. Then add your layer source to the map style's sources and add a layer definition with the specified layer source to the layers list.

Tags