Change the basemap style (v1)

Learn how to change the basemap layer in a map.

The basemap styles service (v1) 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 a number of different basemap layers.

Prerequisites

You need an ArcGIS Developer or ArcGIS Online 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. 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
    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 basemap references

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

    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
          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 getBasemap 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
          const apiKey = "YOUR_API_KEY";
    
          function getBasemap(style) {
            return L.esri.Vector.vectorBasemapLayer(style, {
              apikey: apiKey
            })
          }
    
    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 the basemap layer enumerations. For each enumeration, call the getBasemap function.

    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
          function getBasemap(style) {
            return L.esri.Vector.vectorBasemapLayer(style, {
              apikey: apiKey
            })
          }
    
          const basemapLayers = {
    
            "ArcGIS:Streets": getBasemap("ArcGIS:Streets").addTo(map),
    
            "ArcGIS:Navigation": getBasemap("ArcGIS:Navigation"),
            "ArcGIS:Topographic": getBasemap("ArcGIS:Topographic"),
            "ArcGIS:LightGray": getBasemap("ArcGIS:LightGray"),
            "ArcGIS:DarkGray": getBasemap("ArcGIS:DarkGray"),
            "ArcGIS:StreetsRelief": getBasemap("ArcGIS:StreetsRelief"),
            "ArcGIS:Imagery": getBasemap("ArcGIS:Imagery"),
            "ArcGIS:ChartedTerritory": getBasemap("ArcGIS:ChartedTerritory"),
            "ArcGIS:ColoredPencil": getBasemap("ArcGIS:ColoredPencil"),
            "ArcGIS:Nova": getBasemap("ArcGIS:Nova"),
            "ArcGIS:Midcentury": getBasemap("ArcGIS:Midcentury"),
            "OSM:Standard": getBasemap("OSM:Standard"),
            "OSM:Streets": getBasemap("OSM:Streets")
          };
    
    Expand
  2. Append addTo to the ArcGIS:Streets 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
          function getBasemap(style) {
            return L.esri.Vector.vectorBasemapLayer(style, {
              apikey: apiKey
            })
          }
    
          const basemapLayers = {
    
            "ArcGIS:Streets": getBasemap("ArcGIS:Streets").addTo(map),
    
            "ArcGIS:Navigation": getBasemap("ArcGIS:Navigation"),
            "ArcGIS:Topographic": getBasemap("ArcGIS:Topographic"),
            "ArcGIS:LightGray": getBasemap("ArcGIS:LightGray"),
            "ArcGIS:DarkGray": getBasemap("ArcGIS:DarkGray"),
            "ArcGIS:StreetsRelief": getBasemap("ArcGIS:StreetsRelief"),
            "ArcGIS:Imagery": getBasemap("ArcGIS:Imagery"),
            "ArcGIS:ChartedTerritory": getBasemap("ArcGIS:ChartedTerritory"),
            "ArcGIS:ColoredPencil": getBasemap("ArcGIS:ColoredPencil"),
            "ArcGIS:Nova": getBasemap("ArcGIS:Nova"),
            "ArcGIS:Midcentury": getBasemap("ArcGIS:Midcentury"),
            "OSM:Standard": getBasemap("OSM:Standard"),
            "OSM:Streets": getBasemap("OSM:Streets")
          };
    
    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
          const basemapLayers = {
    
            "ArcGIS:Streets": getBasemap("ArcGIS:Streets").addTo(map),
    
            "ArcGIS:Navigation": getBasemap("ArcGIS:Navigation"),
            "ArcGIS:Topographic": getBasemap("ArcGIS:Topographic"),
            "ArcGIS:LightGray": getBasemap("ArcGIS:LightGray"),
            "ArcGIS:DarkGray": getBasemap("ArcGIS:DarkGray"),
            "ArcGIS:StreetsRelief": getBasemap("ArcGIS:StreetsRelief"),
            "ArcGIS:Imagery": getBasemap("ArcGIS:Imagery"),
            "ArcGIS:ChartedTerritory": getBasemap("ArcGIS:ChartedTerritory"),
            "ArcGIS:ColoredPencil": getBasemap("ArcGIS:ColoredPencil"),
            "ArcGIS:Nova": getBasemap("ArcGIS:Nova"),
            "ArcGIS:Midcentury": getBasemap("ArcGIS:Midcentury"),
            "OSM:Standard": getBasemap("OSM:Standard"),
            "OSM:Streets": getBasemap("OSM:Streets")
          };
    
          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.

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.