Change the basemap style

Learn how to change a basemap styleA basemap layer is the layer in a map or scene that displays basemap data. The data source for a basemap layer is typically a basemap service.Learn more in a mapA map is a collection of layers that are displayed in 2D. It is typically composed of a basemap layer and data layers.Learn more.

The ArcGIS Basemap Styles serviceThe ArcGIS Basemap Styles service, also referred to as the Basemap Styles service, is a location service that provides basemap styles and data for the world. It returns styles as Mapbox styles and web maps, and data as vector tiles and/or map tiles. It supports all of the styles in the ArcGIS Basemap style and Open Basemap style family. An ArcGIS Location Platform or ArcGIS Online account is required to use the service.Learn more provides a number of basemap layer styles such as topography, streets, outdoor, navigation, and imagery that you can use in maps.

In this tutorial, you use the layers control to toggle between a number of different basemap stylesA basemap style is a definition that controls the visual appearance of how geographic data in a basemap are displayed. It includes colors, backgrounds, outlines, labels, and other visual elements. Each basemap style emphasizes a specific type of cartographic theme and data.Learn more.

Prerequisites

Steps

Get the starter app

Select a type of authentication and follow the steps to create a new app.

Set up authentication

Set developer credentials

Use the API key or OAuth developer credentialsDeveloper credentials are a type of item in a portal that contains parameters for authentication. There are two types of developer credentials: API key credentials and OAuth credentials.Learn more so your application can access ArcGIS servicesA service, also known as an ArcGIS service, is software that supports an ArcGIS REST API and provides geospatial functionality or data. A service can be hosted by Esri or in ArcGIS Enterprise.Learn more.

Remove the basemap code

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

   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 map = L.map("map", {
           minZoom: 2
         });
   
         map.setView([30, -20], 3);
   
         const basemapEnum = "arcgis/outdoor";
   
         L.esri.Vector.vectorBasemapLayer(basemapEnum, {
           token: accessToken
         }).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. Include your API key to validate the call.

   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
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
       function getV2Basemap(style) {
         return L.esri.Vector.vectorBasemapLayer(style, {
           token: accessToken
         });
       }
   

   Expand

Add the basemap styles

Reference the basemap stylesA basemap style is a definition that controls the visual appearance of how geographic data in a basemap are displayed. It includes colors, backgrounds, outlines, labels, and other visual elements. Each basemap style emphasizes a specific type of cartographic theme and data.Learn more you would like to use in your application.

1. Use L.esri.get to make a request to the Basemap Styles service. This dynamically fetches the available basemap styles. For each enumerated style, call the getV2Basemap function to populate the styles list.

   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
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
       function getV2Basemap(style) {
         return L.esri.Vector.vectorBasemapLayer(style, {
           token: accessToken
         });
       }
   
       L.esri.get(
         "https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/self",
         { token: accessToken },
         (error, response) => {
           if (error) {
             console.error("Error fetching basemap styles:", error);
             return;
           }
   
           const styles = {};
           let firstStyleLayer; // Store the first style layer
   
           const basemapStyles = response.styles.filter((style) => !style.deprecated);
           basemapStyles.forEach((style, index) => {
             const layer = getV2Basemap(style.path);
             styles[style.name] = layer;
   
           });
   
         }
       );
   

   Expand

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

   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
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
       function getV2Basemap(style) {
         return L.esri.Vector.vectorBasemapLayer(style, {
           token: accessToken
         });
       }
   
       L.esri.get(
         "https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/self",
         { token: accessToken },
         (error, response) => {
           if (error) {
             console.error("Error fetching basemap styles:", error);
             return;
           }
   
           const styles = {};
           let firstStyleLayer; // Store the first style layer
   
           const basemapStyles = response.styles.filter((style) => !style.deprecated);
           basemapStyles.forEach((style, index) => {
             const layer = getV2Basemap(style.path);
             styles[style.name] = layer;
   
             if (index === 0) {
               firstStyleLayer = layer;
               firstStyleLayer.addTo(map);
             }
   
           });
   
         }
       );
   

   Expand

3. Create a Layers control that references basemapLayers 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
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
       L.esri.get(
         "https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/self",
         { token: accessToken },
         (error, response) => {
           if (error) {
             console.error("Error fetching basemap styles:", error);
             return;
           }
   
           const styles = {};
           let firstStyleLayer; // Store the first style layer
   
           const basemapStyles = response.styles.filter((style) => !style.deprecated);
           basemapStyles.forEach((style, index) => {
             const layer = getV2Basemap(style.path);
             styles[style.name] = layer;
   
             if (index === 0) {
               firstStyleLayer = layer;
               firstStyleLayer.addTo(map);
             }
   
           });
   
           L.control.layers(styles, null, { collapsed: false }).addTo(map);
   

   Expand

Run the app

Run the app.

Use the layers control in the top right to select and explore different basemap layer styles from the Basemap Styles serviceThe ArcGIS Basemap Styles service, also referred to as the Basemap Styles service, is a location service that provides basemap styles and data for the world. It returns styles as Mapbox styles and web maps, and data as vector tiles and/or map tiles. It supports all of the styles in the ArcGIS Basemap style and Open Basemap style family. An ArcGIS Location Platform or ArcGIS Online account is required to use the service.Learn more.

What's next?

Learn how to use additional location services in these tutorials: