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
- 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.
-
Go to your dashboard to get an API key. The API key must be scoped to access the services used in this tutorial.
-
In CodePen, update
api
to use your key.Key Use dark colors for code blocks 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
-
Remove the
basemap
andEnum vector
references contained in the .Basemap Layer Use dark colors for code blocks 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);
Create a basemap style function
Create a function that accepts a basemap style enumeration and returns the corresponding basemap style.
-
Define a new
get
function that accepts a style enumeration and returns aBasemap Vector
. Include your API key to validate the call.Basemap Layer Use dark colors for code blocks const apiKey = "YOUR_API_KEY"; function getBasemap(style) { return L.esri.Vector.vectorBasemapLayer(style, { apikey: apiKey }) }
Add the basemap styles
Reference the additional basemap styles you would like to use in your application.
-
Create a
basemap
object that contains the labels for the basemap layer enumerations. For each enumeration, call theLayers get
function.Basemap Use dark colors for code blocks 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") };
-
Append
add
to theT o ArcGIS:
entry so that it is the default style when the application loads.Streets Use dark colors for code blocks 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") };
-
Create a
Layers
control that referencesbasemap
and add it to your map.Layers Use dark colors for code blocks 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);
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:
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.