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 a free ArcGIS developer account to access your dashboard and API keys. The API key must be scoped to access the services used in this tutorial.

Steps

Create a new pen

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

Set the API key

To access ArcGIS location services, you need an API key.

  1. Go to your dashboard to get an API key.

  2. In CodePen, update apiKey to use your key.

    Change line
                                                             
    <!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.
                                                                             
<!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: