Change the basemap style (v2)

Learn how to change a basemap style in a map using the Basemap styles service v2.

The basemap styles service provides a number of basemap layer styles such as topography, streets, and imagery that you can use in maps. The basemap styles service v2 provides additional styles such as ArcGIS Outdoor, OSM Navigation, and OSM Blueprint. This v2 service is recommended for use in your application, as it will be the primary focus of future development.

In this tutorial, you use the layers control to toggle between a number of different basemap styles.

Prerequisites

Steps

Create a new pen

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

Set the API key

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. 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

                                                             

   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
   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);
   

Remove the basemap code

1. Remove the basemapEnum and vectorBasemapLayer references contained in the starter code.

   Expand

   Use dark colors for code blocks

                                                             

   Remove lineRemove lineRemove lineRemove 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
         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);
   

   Expand

Create a basemap style function

Create a function that accepts a basemap style enumeration and returns the corresponding basemap style

1. Define a new getV2Basemap function that accepts a style enumeration and returns a VectorBasemapLayer. Set version:2 to access the v2 styles service, and include your API key to validate the call.

   Expand

   Use dark colors for code blocks

                                                                                   

   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
   78
   79
   80
         const apiKey = "YOUR_API_KEY";
   
         function getV2Basemap(style) {
           return L.esri.Vector.vectorBasemapLayer(style, {
             apikey: apiKey,
             version:2
           })
         }
   

   Expand

Add the basemap styles

Reference the additional basemap styles you would like to use in your application.

1. Create a basemapLayers object that contains the labels for each basemap layer enumeration. For each enumeration, call the getV2Basemap function to populate basemapLayers.

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
78
79
80
      function getV2Basemap(style) {
        return L.esri.Vector.vectorBasemapLayer(style, {
          apikey: apiKey,
          version:2
        })
      }

      const basemapLayers = {

        "arcgis/outdoor": getV2Basemap("arcgis/outdoor").addTo(map),

        "arcgis/community": getV2Basemap("arcgis/community"),
        "arcgis/navigation": getV2Basemap("arcgis/navigation"),
        "arcgis/streets": getV2Basemap("arcgis/streets"),
        "arcgis/streets-relief": getV2Basemap("arcgis/streets-relief"),
        "arcgis/imagery": getV2Basemap("arcgis/imagery"),
        "arcgis/oceans": getV2Basemap("arcgis/oceans"),
        "arcgis/topographic": getV2Basemap("arcgis/topographic"),
        "arcgis/light-gray": getV2Basemap("arcgis/light-gray"),
        "arcgis/dark-gray": getV2Basemap("arcgis/dark-gray"),
        "arcgis/human-geography": getV2Basemap("arcgis/human-geography"),
        "arcgis/charted-territory": getV2Basemap("arcgis/charted-territory"),
        "arcgis/nova": getV2Basemap("arcgis/nova"),
        "osm/standard": getV2Basemap("osm/standard"),
        "osm/navigation": getV2Basemap("osm/navigation"),
        "osm/streets": getV2Basemap("osm/streets"),
        "osm/blueprint": getV2Basemap("osm/blueprint")
      };

1. Append addTo to the arcgis/outdoor entry so that it is the default style when the application loads.

   Expand

   Use dark colors for code blocks

                                                                                   

   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
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
         function getV2Basemap(style) {
           return L.esri.Vector.vectorBasemapLayer(style, {
             apikey: apiKey,
             version:2
           })
         }
   
         const basemapLayers = {
   
           "arcgis/outdoor": getV2Basemap("arcgis/outdoor").addTo(map),
   
           "arcgis/community": getV2Basemap("arcgis/community"),
           "arcgis/navigation": getV2Basemap("arcgis/navigation"),
           "arcgis/streets": getV2Basemap("arcgis/streets"),
           "arcgis/streets-relief": getV2Basemap("arcgis/streets-relief"),
           "arcgis/imagery": getV2Basemap("arcgis/imagery"),
           "arcgis/oceans": getV2Basemap("arcgis/oceans"),
           "arcgis/topographic": getV2Basemap("arcgis/topographic"),
           "arcgis/light-gray": getV2Basemap("arcgis/light-gray"),
           "arcgis/dark-gray": getV2Basemap("arcgis/dark-gray"),
           "arcgis/human-geography": getV2Basemap("arcgis/human-geography"),
           "arcgis/charted-territory": getV2Basemap("arcgis/charted-territory"),
           "arcgis/nova": getV2Basemap("arcgis/nova"),
           "osm/standard": getV2Basemap("osm/standard"),
           "osm/navigation": getV2Basemap("osm/navigation"),
           "osm/streets": getV2Basemap("osm/streets"),
           "osm/blueprint": getV2Basemap("osm/blueprint")
         };
   

   Expand

2. Create a Layers control that references basemapLayers and add it to your map.

   Expand

   Use dark colors for code blocks

                                                                                   

   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
   78
   79
   80
         const basemapLayers = {
   
           "arcgis/outdoor": getV2Basemap("arcgis/outdoor").addTo(map),
   
           "arcgis/community": getV2Basemap("arcgis/community"),
           "arcgis/navigation": getV2Basemap("arcgis/navigation"),
           "arcgis/streets": getV2Basemap("arcgis/streets"),
           "arcgis/streets-relief": getV2Basemap("arcgis/streets-relief"),
           "arcgis/imagery": getV2Basemap("arcgis/imagery"),
           "arcgis/oceans": getV2Basemap("arcgis/oceans"),
           "arcgis/topographic": getV2Basemap("arcgis/topographic"),
           "arcgis/light-gray": getV2Basemap("arcgis/light-gray"),
           "arcgis/dark-gray": getV2Basemap("arcgis/dark-gray"),
           "arcgis/human-geography": getV2Basemap("arcgis/human-geography"),
           "arcgis/charted-territory": getV2Basemap("arcgis/charted-territory"),
           "arcgis/nova": getV2Basemap("arcgis/nova"),
           "osm/standard": getV2Basemap("osm/standard"),
           "osm/navigation": getV2Basemap("osm/navigation"),
           "osm/streets": getV2Basemap("osm/streets"),
           "osm/blueprint": getV2Basemap("osm/blueprint")
         };
   
         L.control.layers(basemapLayers, null, { collapsed: false }).addTo(map);
   

   Expand

Run the app

In CodePen, run your code to display the map.

Use the layers control in the top right to select and explore different basemap layer styles from the Basemap styles service (v2).

What's next?

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

Change the basemap style (v2)

Switch a basemap style in a map using the basemap styles service v2.

Change the place label language

Switch the language of place labels on a basemap.

Display a custom basemap style

Add a styled vector basemap layer to a map.

Style vector tiles

Change the fill and outline of vector tiles based on their attributes.