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 hillshade map tile layer to your map and display it beneath a semitransparent basemap layer.

Prerequisites

Steps

Create a new pen

To access location services, you need an API key or OAuth 2.0 access token. To learn how to create and scope your key, visit the Create an API key tutorial.

1. To get started, either complete the Display a map tutorial or use this pen.

Set the API key

1. Go to your dashboard to get an API key. The API key must be scoped to access the services used in this tutorial.

2. In CodePen, update apiKey to use your key.

   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 apiKey = "YOUR_API_KEY";
   
         const basemapEnum = "arcgis/streets";
   
         L.esri.Vector.vectorBasemapLayer(basemapEnum, {
           apiKey: apiKey
         }).addTo(map);
   

Add a map tile layer

Use the TiledMapLayer class to access and display data from the World Hillshade map tile service.

1. Access the hillshade 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
         L.esri.Vector.vectorBasemapLayer(basemapEnum, {
           apiKey: apiKey,
   
         }).addTo(map);
   
         L.esri.tiledMapLayer({
           url:"https://server.arcgisonline.com/arcgis/rest/services/Elevation/World_Hillshade/MapServer",
           apiKey: apiKey,
   
         }).addTo(map);
   
       </script>
   

   Expand

Reposition and style the basemap

By default, the basemap layer is added to the same pane as the hillshade layer. To visuallly combine hillshading with a basemap, you need to change the layer order and opacity of the basemap so both layers are visible.

1. Create a new Leaflet pane called esri-basemap. Set the zIndex of the pane to 300 to display above the hillshade 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
         const basemapPane = map.createPane('esri-basemap');
         basemapPane.style.zIndex = 300;
   
         L.esri.Vector.vectorBasemapLayer(basemapEnum, {
           apiKey: apiKey,
   
           pane: basemapPane,
   
         }).addTo(map);
   

   Expand

2. Reduce the opacity of everything in the basemap layer except for water and buildings. This will make the hillshade layer visible on land.

   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
         L.esri.Vector.vectorBasemapLayer(basemapEnum, {
           apiKey: apiKey,
   
           pane: basemapPane,
   
           style: function (style) {
             for (const [i, layer] of style.layers.entries()) {
               if (layer.type === 'fill' && !layer.id.match(/(Water|Marine|Bathymetry|Building)/)) {
                 style.layers[i].paint['fill-opacity'] = 0.5;
               }
             }
             return style
           }
   
         }).addTo(map);
   

   Expand

Run the app

In CodePen, run your code to display the map.

Your map should display a hillshade layer underneath a semi-transparent basemap. You should see the hillshade 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: