Learn how to change a basemap style in a map.
The ArcGIS Basemap Styles service provides a number of basemap styles such as topography, streets, outdoor, navigation, and imagery that you can use in maps. To access these basemap styles in your MapLibre GL JS app, use the MapLibre ArcGIS plugin.
In this tutorial, use a <select
dropdown menu to toggle between different basemap styles.
Prerequisites
You need an ArcGIS Location Platform or ArcGIS Online account.
Steps
Get the starter app
Select a type of authentication below and follow the steps to create a new application.
Set up authentication
Create developer credentials in your portal for the type of authentication you selected.
Set developer credentials
Use the API key or OAuth developer credentials so your application can access ArcGIS services.
Add a style selector
-
In the wrapper element, add a
<select
element, which you will populate in a later step.> Use dark colors for code blocks </style> <!-- Load MapLibre GL JS from CDN --> <script src=https://unpkg.com/maplibre-gl@5.8.0/dist/maplibre-gl.js></script> <link href=https://unpkg.com/maplibre-gl@5.8.0/dist/maplibre-gl.css rel="stylesheet" /> <!-- Load MapLibre ArcGIS from CDN --> <script src="https://unpkg.com/@esri/maplibre-arcgis@1.0.0/dist/umd/maplibre-arcgis.min.js"></script> </head> <body> <div id="map"></div> <div id="basemaps-wrapper"> <select id="basemaps"></select> </div>
-
In the
<style
element, add CSS styling to the> basemaps-wrapper
andbasemaps
.Use dark colors for code blocks <style> html, body, #map { padding: 0; margin: 0; height: 100%; width: 100%; font-family: Arial, Helvetica, sans-serif; font-size: 14px; color: #323232; } #basemaps-wrapper { position: absolute; top: 20px; right: 20px; background: rgba(255, 255, 255, 0); } #basemaps { font-size: 16px; padding: 4px 8px; } </style> <!-- Load MapLibre GL JS from CDN --> <script src=https://unpkg.com/maplibre-gl@5.8.0/dist/maplibre-gl.js></script> <link href=https://unpkg.com/maplibre-gl@5.8.0/dist/maplibre-gl.css rel="stylesheet" /> <!-- Load MapLibre ArcGIS from CDN --> <script src="https://unpkg.com/@esri/maplibre-arcgis@1.0.0/dist/umd/maplibre-arcgis.min.js"></script>
Set the basemap
Using the MapLibre ArcGIS plugin, reference the Basemap Styles service and a style enumeration to update the map. This will be used when a selection is made.
-
Comment out the map style as it will be updated dynamically based on the user's selection.
Use dark colors for code blocks // const basemapStyle = maplibreArcGIS.BasemapStyle.applyStyle(map, { // style: 'arcgis/outdoor', // token: accessToken // });
-
Define a function to update the map style using the selected basemap layer.
Use dark colors for code blocks const setBasemap = (selection) => { const basemapStyle = maplibreArcGIS.BasemapStyle.applyStyle(map, { style: selection, token: accessToken }); };
-
Select the DOM element used for the basemap selector.
Use dark colors for code blocks const basemapsSelectElement = document.querySelector("#basemaps");
-
Use the MapLibre ArcGIS plugin to make a request to the Basemap Styles service. This dynamically fetches the available basemap styles and populates the
select
element.Use dark colors for code blocks maplibreArcGIS.BasemapStyle.getSelf().then(response => { const basemapStyles = response.styles.filter(style => !style.deprecated) basemapStyles.forEach(style => { const option = document.createElement("option"); option.value = style.path; option.textContent = style.name; basemapsSelectElement.appendChild(option); }); })
-
Initialize the basemap layer with the first style returned from the response. This ensures the map loads with a default style when the page first loads.
Use dark colors for code blocks maplibreArcGIS.BasemapStyle.getSelf().then(response => { const basemapStyles = response.styles.filter(style => !style.deprecated) basemapStyles.forEach(style => { const option = document.createElement("option"); option.value = style.path; option.textContent = style.name; basemapsSelectElement.appendChild(option); }); setBasemap(response.styles[0].path); })
-
Run the code to ensure that the
<select
element contains different basemap enumerations.>
Add an event listener
Call set
when the user selects an option in the <select
menu.
-
Add an event listener to update the map to the new basemap when the selector is changed.
Use dark colors for code blocks const basemapsSelectElement = document.querySelector("#basemaps"); maplibreArcGIS.BasemapStyle.getSelf().then(response => { const basemapStyles = response.styles.filter(style => !style.deprecated) basemapStyles.forEach(style => { const option = document.createElement("option"); option.value = style.path; option.textContent = style.name; basemapsSelectElement.appendChild(option); }); setBasemap(response.styles[0].path); }) basemapsSelectElement.addEventListener("change", (e) => { setBasemap(e.target.value); });
Run the app
Run the app.
Try selecting different basemap styles from the selector. As you select the different styles, you should see the basemap change accordingly.What's next?
Learn how to use additional location services in these tutorials:

Change the basemap style
Switch a vector basemap style on a map.

Change language labels for basemap styles
Switch the language of place labels on a basemap.

Display a custom basemap style
Add a custom vector basemap style to a map.

Display basemap places
Display places of interest on a basemap and get place details.

Change the static basemap tiles style
Switch a static basemap style on a map.