Change the basemap style

Learn how to change a in a .

Change the basemap style using API key authentication

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

Prerequisites

Steps

Get the starter app

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

You can choose one of the following to create a new CodePen:

  • Option 1: Complete the Display a map tutorial; or,
  • Option 2: Start from the Display a map tutorial .

Set up authentication

Create in your for the type of authentication you selected.

Create a new with to access the resources used in this tutorial.

  1. Go to the Create an API key tutorial and create an with the following :
    • Privileges
      • Location services > Basemaps
  2. When prompted, copy and paste the API key to a safe location. It will be used in the next step.

Set developer credentials

Use the API key or OAuth so your application can access .

  1. Update the accessToken variable to use your API key.

    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
      <script>
    
        /* Use for API key authentication */
        const accessToken = "YOUR_ACCESS_TOKEN";
    
        const map = L.map("map", {
          minZoom: 2
        })
    
        map.setView([34.02, -118.805], 13);
    
        const basemapEnum = "arcgis/streets";
    
        L.esri.Vector.vectorBasemapLayer(basemapEnum, {
          token: accessToken
        }).addTo(map);
    
      </script>
    

Remove the basemap code

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

    Expand
    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
        const map = L.map("map", {
          minZoom: 2
        })
    
        map.setView([34.02, -118.805], 13);
    
        const basemapEnum = "arcgis/streets";
    
        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. Set version:2 to access the styles service, and include your API key to validate the call.

    Expand
    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
        function getV2Basemap(style) {
          return L.esri.Vector.vectorBasemapLayer(style, {
            token: accessToken,
            version: 2
          })
        }
    
    Expand

Add the basemap styles

Reference the additional 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.

    Expand
    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
        function getV2Basemap(style) {
          return L.esri.Vector.vectorBasemapLayer(style, {
            token: accessToken,
            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. Append addTo to the arcgis/outdoor entry so that it is the default style when the application loads.

    Expand
    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
        function getV2Basemap(style) {
          return L.esri.Vector.vectorBasemapLayer(style, {
            token: accessToken,
            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
  3. Create a Layers control that references basemapLayers and add it to your map.

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

Run the app.

Use the layers control in the top right to select and explore different basemap layer styles from the .

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.

You can no longer sign into this site. Go to your ArcGIS portal or the ArcGIS Location Platform dashboard to perform management tasks.

Your ArcGIS portal

Create, manage, and access API keys and OAuth 2.0 developer credentials, hosted layers, and data services.

Your ArcGIS Location Platform dashboard

Manage billing, monitor service usage, and access additional resources.

Learn more about these changes in the What's new in Esri Developers June 2024 blog post.

Close

Supported

Supported

Not supported. Learn more