Change the basemap layer

Learn how to change the basemap layer in a map.

The basemap layer service provides a number of basemap layer styles such as topography, streets, and imagery that you can use in maps.

In this tutorial, you use the layers control to toggle between the different basemap layers.

Prerequisites

You need an ArcGIS account to access the developer dashboard and create an API key.

Steps

Create a new pen

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

Set the API key

To access location services, you need an API key or OAuth 2.0 access token.

  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.

    Change line
                                                             
    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
    <!DOCTYPE html>
    <html>
    
    <head>
      <meta charset="utf-8">
      <meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no" />
      <title>Esri Leaflet</title>
    
      <!-- Load Leaflet from CDN -->
      <link rel="stylesheet" href="https://unpkg.com/leaflet@1.7.1/dist/leaflet.css"
        integrity="sha512-xodZBNTC5n17Xt2atTPuE1HxjVMSvLVW9ocqUKLsCC5CXdbqCmblAshOMAS6/keqq/sMZMZ19scR4PsZChSR7A=="
        crossorigin=""/>
      <script src="https://unpkg.com/leaflet@1.7.1/dist/leaflet.js"
        integrity="sha512-XQoYMqMTK8LvdxXYG3nZ448hOEQiglfqkJs1NOQV44cWnUrBc8PkAOcXy20w0vlaXaVUearIOBhiXZ5V3ynxwA=="
        crossorigin=""></script>
    
      <!-- Load Esri Leaflet from CDN -->
      <script src="https://unpkg.com/esri-leaflet@3.0.0/dist/esri-leaflet.js"></script>
      <script src="https://unpkg.com/esri-leaflet-vector@3.0.0/dist/esri-leaflet-vector.js"></script>
    
      <style>
        body { margin:0; padding:0; }
        #map {
            position: absolute;
            top:0;
            bottom:0;
            right:0;
            left:0;
            font-family: Arial, Helvetica, sans-serif;
            font-size: 14px;
            color: #323232;
      </style>
    
    </head>
    
    <body>
      <div id="map"></div>
    
      <script>
        const apiKey = "YOUR_API_KEY";
        const basemapEnum = "ArcGIS:Streets";
    
        const map = L.map('map', {
          minZoom: 2
        }).setView([34.02,-118.805], 13);
    
        L.esri.Vector.vectorBasemapLayer(basemapEnum, {
          apiKey: apiKey
        }).addTo(map);
      </script>
    
    </body>
    
    </html>

Change the basemap layer

Update and add the following code to change the basemap layer with a control.

  • Remove the add basemap layer code.
  • Create an object to reference the basemap layer styles.
  • Add the layers control with the basemap layers list.
Remove lineRemove lineRemove lineRemove lineAdd line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
                                                                             
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
75
76
77
<!DOCTYPE html>
<html>

<head>
  <meta charset="utf-8">
  <meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no" />
  <title>Esri Leaflet</title>

  <!-- Load Leaflet from CDN -->
  <link rel="stylesheet" href="https://unpkg.com/leaflet@1.7.1/dist/leaflet.css"
    integrity="sha512-xodZBNTC5n17Xt2atTPuE1HxjVMSvLVW9ocqUKLsCC5CXdbqCmblAshOMAS6/keqq/sMZMZ19scR4PsZChSR7A=="
    crossorigin=""/>
<script src="https://unpkg.com/leaflet@1.7.1/dist/leaflet.js"
    integrity="sha512-XQoYMqMTK8LvdxXYG3nZ448hOEQiglfqkJs1NOQV44cWnUrBc8PkAOcXy20w0vlaXaVUearIOBhiXZ5V3ynxwA=="
    crossorigin=""></script>

  <!-- Load Esri Leaflet from CDN -->
  <script src="https://unpkg.com/esri-leaflet@3.0.0/dist/esri-leaflet.js"></script>
  <script src="https://unpkg.com/esri-leaflet-vector@3.0.0/dist/esri-leaflet-vector.js"></script>

  <style>
    body { margin:0; padding:0; }
    #map {
      position: absolute;
      top:0;
      bottom:0;
      right:0;
      left:0;
      font-family: Arial, Helvetica, sans-serif;
      font-size: 14px;
      color: #323232;
  </style>

</head>

<body>

  <div id="map"></div>

  <script>
    const apiKey = "YOUR_API_KEY";

    // const basemapEnum = "ArcGIS:Streets";

    const map = L.map('map', {
      minZoom: 2
    }).setView([34.02,-118.805], 13);

    // L.esri.Vector.vectorBasemapLayer(basemapEnum, {
    //   apiKey: apiKey
    // }).addTo(map);

    const basemapLayers = {
      "Streets": L.esri.Vector.vectorBasemapLayer('ArcGIS:Streets', {apiKey: apiKey}).addTo(map),
      "Navigation": L.esri.Vector.vectorBasemapLayer('ArcGIS:Navigation', {apiKey: apiKey}).addTo(map),
      "Topographic": L.esri.Vector.vectorBasemapLayer('ArcGIS:Topographic', {apiKey: apiKey}).addTo(map),
      "Light Gray": L.esri.Vector.vectorBasemapLayer('ArcGIS:LightGray', {apiKey: apiKey}).addTo(map),
      "Dark gray": L.esri.Vector.vectorBasemapLayer('ArcGIS:DarkGray', {apiKey: apiKey}).addTo(map),
      "Streets Relief": L.esri.Vector.vectorBasemapLayer('ArcGIS:StreetsRelief', {apiKey: apiKey}).addTo(map),
      "Imagery": L.esri.Vector.vectorBasemapLayer('ArcGIS:Imagery', {apiKey: apiKey}).addTo(map),
      "ChartedTerritory": L.esri.Vector.vectorBasemapLayer('ArcGIS:ChartedTerritory', {apiKey: apiKey}).addTo(map),
      "ColoredPencil": L.esri.Vector.vectorBasemapLayer('ArcGIS:ColoredPencil', {apiKey: apiKey}).addTo(map),
      "Nova": L.esri.Vector.vectorBasemapLayer('ArcGIS:Nova', {apiKey: apiKey}).addTo(map),
      "Midcentury": L.esri.Vector.vectorBasemapLayer('ArcGIS:Midcentury', {apiKey: apiKey}).addTo(map),
      "OSM": L.esri.Vector.vectorBasemapLayer('OSM:Standard', {apiKey: apiKey}).addTo(map),
      "OSM:Streets": L.esri.Vector.vectorBasemapLayer('OSM:Streets', {apiKey: apiKey}).addTo(map)
    }

    L.control.layers(basemapLayers).addTo(map);
  </script>

</body>

</html>

Run the app

In CodePen, run your code to display the map.

Click the layers control to change the basemap layer.

What's next

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

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.