Add a map tile layer

Learn how to add a map tile layer to a map.

A map tile layer, also known as an image tile layer, displays raster imagery such as satellite photography or hillshading. You can combine map tile layers to enhance the display of a street basemap layer, position the layer on top of existing layers, or position it under existing layers. When positioned above other layers, you need to give the map tile layer a level of transparency so that users can see through it to the basemap. This combined basemap layer technique is used to enhance overall visualization.

In this tutorial, you add a Santa Monica contours map tile layer to your map.

Prerequisites

Steps

Create a new pen

You need an access token with the correct privileges to access the resources used in this tutorial.

1. Go to the Create an API key tutorial and create an API key with the following privilege(s):
   
   • Privileges
     • Location services > Basemaps
2. Copy the API key access token as it will be used in the next step.

To learn about other ways to get an access token, go to Types of authentication.

1. To get started, you can complete the Display a map tutorial or use the Display a map tutorial solution (CodePen).

Get an access token

You need an access token with the correct privileges to access the resources used in this tutorial.

1. Go to the Create an API key tutorial and create an API key with the following privilege(s):
   

   • Privileges
     • Location services > Basemaps
   • Item access
     • Note: If you are using your own custom data layer for this tutorial, you need to grant the API key credentials access to the layer item. Learn more in Item access privileges.

2. Copy the API key access token to your clipboard when prompted.

3. In CodePen, update the accessToken variable to use your access token.

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
         const map = L.map("map", {
           minZoom: 2
         })
   
         map.setView([34.02, -118.805], 13);
   
         const accessToken = "YOUR_ACCESS_TOKEN";
   
         const basemapEnum = "arcgis/streets";
   
         L.esri.Vector.vectorBasemapLayer(basemapEnum, {
           token: accessToken
         }).addTo(map);
   

4. Run the code to ensure the basemap is displayed in the map.

To learn about the other types of authentication available, go to Types of authentication.

Update the map

1. Center the map on [-118.44, 34.03] and set the zoom level to 11. This will set the map focus to Santa Monica, California.

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
         const accessToken = "YOUR_ACCESS_TOKEN";
         const basemapEnum = "arcgis/light-gray";
   
         const map = L.map("map", {
           minZoom: 2
         }).setView([34.03, -118.44], 11);
   

   Expand

Add a map tile layer

Use the TiledMapLayer class to access and display data from the Santa Monica contours map tile service.

1. Access the contours layer with a TiledMapLayer and add it to your map.

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
         L.esri.Vector.vectorBasemapLayer(basemapEnum, {
           token: accessToken,
   
         }).addTo(map);
   
   
         const contoursLayer = L.esri.tiledMapLayer({
           url:"https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Santa_Monica_contours_(map_tiles)/MapServer/",
           apiKey: accessToken,
   
         })
   
         contoursLayer.addTo(map)
   
       </script>
   

   Expand

2. Set the opacity of the contours layer to 0.5.

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
         L.esri.Vector.vectorBasemapLayer(basemapEnum, {
           token: accessToken,
   
         }).addTo(map);
   
   
         const contoursLayer = L.esri.tiledMapLayer({
           url:"https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Santa_Monica_contours_(map_tiles)/MapServer/",
           apiKey: accessToken,
   
         })
   
         contoursLayer.addTo(map)
   
         contoursLayer.setOpacity(0.5);
   
       </script>
   

   Expand

Reorder the layers

By default, the basemap layer is added to the same pane as the contours layer. To visually combine the contours with a basemap, you need to change the layer order so both layers are visible.

1. Create a new Leaflet pane called esri-basemap. Set the zIndex of the pane to 200 to display below the contours layer. Add code so the basemap is created in the new pane.

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
         const basemapPane = map.createPane('esri-basemap');
         basemapPane.style.zIndex = 200;
   
         L.esri.Vector.vectorBasemapLayer(basemapEnum, {
           token: accessToken,
   
           pane: basemapPane,
   
         }).addTo(map);
   

   Expand

2. Create another pane called contours for the Hillshade layer. Set the zIndex to 400 to display above the basemap. Add code so the Hillshade layer is created in the new pane.

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   
         const contoursPane = map.createPane('contours')
         contoursPane.style.zIndex = 400;
   
         const contoursLayer = L.esri.tiledMapLayer({
           url:"https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Santa_Monica_contours_(map_tiles)/MapServer/",
           apiKey: accessToken,
   
           pane: contoursPane
   
         })
   
         contoursLayer.addTo(map)
   
         contoursLayer.setOpacity(0.5);
   
       </script>
   

   Expand

Run the app

In CodePen, run your code to display the map.

Your map should display a semi-transparent contours layer on top of a basemap. You should see the contours layer combined with other layers, with labels, roads, buildings and water areas clearly visible over the top.

What's next?

Learn how to use additional ArcGIS location services in these tutorials: