Change the basemap style | ArcGIS Maps SDK for JavaScript

Learn how to change the basemap style A basemap layer is the layer in a map or scene that displays basemap data. The data source for a basemap layer is typically a basemap service. Learn more in a map A map is a collection of layers that are displayed in 2D. It is typically composed of a basemap layer and data layers. Learn more using the Basemap styles service The ArcGIS Basemap Styles service, also referred to as the Basemap Styles service, is a location service that provides basemap styles and data for the world. It returns styles as Mapbox styles and web maps, and data as vector tiles and/or map tiles. It supports all of the styles in the ArcGIS Basemap style and Open Basemap style family. An ArcGIS Location Platform or ArcGIS Online account is required to use the service. Learn more .

The basemap styles service The ArcGIS Basemap Styles service, also referred to as the Basemap Styles service, is a location service that provides basemap styles and data for the world. It returns styles as Mapbox styles and web maps, and data as vector tiles and/or map tiles. It supports all of the styles in the ArcGIS Basemap style and Open Basemap style family. An ArcGIS Location Platform or ArcGIS Online account is required to use the service. Learn more provides a number of ArcGIS basemap layer styles such as topography, navigation, outdoors, and imagery that you can use in maps.

In this tutorial, you will use a Calcite Combobox to select and display different basemap styles A basemap style is a definition that controls the visual appearance of how geographic data in a basemap are displayed. It includes colors, backgrounds, outlines, labels, and other visual elements. Each basemap style emphasizes a specific type of cartographic theme and data. Learn more .

Prerequisites

Steps

Create a new pen

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

Get an access token

You need an access token An access token is an authorization string that provides access to secure ArcGIS content, data, and services. Its capabilities are determined by the privileges it supports. It is obtained by implementing API key authentication, User authentication, or App authentication. Learn more with the correct privileges to access the location services ArcGIS Location Services, also referred to as Location Services, are services hosted by Esri that provide geospatial functionality for developing mapping applications. They include the ArcGIS Basemap Styles service, ArcGIS Static Basemap Tiles service, ArcGIS Places service, ArcGIS Geocoding service, ArcGIS Routing service, ArcGIS GeoEnrichment service, and ArcGIS Elevation service. An ArcGIS Location Platform or ArcGIS Online account is required to use the services. Learn more used in this tutorial.

Go to the Create an API key tutorial and create an API key An API key is a long-lived access token created using API key credentials. They are valid for up to one year and are typically embedded directly into client applications. Learn more with the following privilege(s) Privileges are a set of permissions assigned to ArcGIS accounts, developer credentials, and applications that grant access to secure resources and functionality in ArcGIS. Learn more :
- Privileges
  - Location services > Basemaps
In CodePen, set the apiKey property on the global esriConfig variable to your access token.
var esriConfig = { apiKey: "YOUR_ACCESS_TOKEN", };

To learn about other ways to get an access token, go to Types of authentication.

Add modules

The request module can be used to request data from a remote server or file. We’ll use this module to fetch the available styles from the basemap style API endpoint.

In a new <script> at the bottom of the <body>, use $arcgis.import() to add the request module.

The ArcGIS Maps SDK for JavaScript ArcGIS Maps SDK for JavaScript, previously known as ArcGIS API for JavaScript, is a developer product for building mapping and spatial analysis applications for the web. Learn more is available via CDN and npm, but this tutorial is based on CDN. The $arcgis.import global function accepts a module path or array of module paths, and returns a promise that resolves with the requested modules. This function can only be used when working with the CDN; otherwise, use the standard import syntax. To learn more about the SDK’s different modules, visit the References page.

34 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>ArcGIS Maps SDK for JavaScript Tutorials: Change the basemap style</title>
  <style>
    html,
    body {
      height: 100%;
      margin: 0;
    }


  </style>

  <script>
    var esriConfig = {
      apiKey: "YOUR_ACCESS_TOKEN",
    };
  </script>

  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>

</head>

<body>

  <arcgis-map basemap="arcgis/topographic" center="-118.805, 34.020" zoom="13">
    <arcgis-zoom slot="top-left"></arcgis-zoom>

  </arcgis-map>

  <script type="module">
    const esriRequest = await $arcgis.import("@arcgis/core/request.js");

  </script>
4 collapsed lines

</body>

</html>

Get the list of styles available from the basemap style service and add them to a calcite-combobox component to allow users to change the style of their basemap.

Create a div called basemapStyles with a calcite-combobox component, placed in the top-right slot of the map. Set selection-mode to single, so only one style can be selected at a time. Add the clear-disabled attribute so that a style is always selected.

29 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>ArcGIS Maps SDK for JavaScript Tutorials: Change the basemap style</title>
  <style>
    html,
    body {
      height: 100%;
      margin: 0;
    }


  </style>

  <script>
    var esriConfig = {
      apiKey: "YOUR_ACCESS_TOKEN",
    };
  </script>

  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>

</head>

<body>

  <arcgis-map basemap="arcgis/topographic" center="-118.805, 34.020" zoom="13">
    <arcgis-zoom slot="top-left"></arcgis-zoom>

    <div id="basemapStyles" slot="top-right">
      <calcite-label>
        Basemap Style:
        <calcite-combobox id="styleCombobox" selection-mode="single" clear-disabled></calcite-combobox>
      </calcite-label>
    </div>

  </arcgis-map>
9 collapsed lines

  <script type="module">
    const esriRequest = await $arcgis.import("@arcgis/core/request.js");

  </script>

</body>

</html>

Within the <style> tags, apply some CSS properties to the basemapStyles div.

14 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>ArcGIS Maps SDK for JavaScript Tutorials: Change the basemap style</title>
  <style>
    html,
    body {
      height: 100%;
      margin: 0;
    }


    #basemapStyles {
      background-color: white;
      border-radius: 5px;
      padding: 10px;
      width: 250px;
    }

36 collapsed lines

  </style>

  <script>
    var esriConfig = {
      apiKey: "YOUR_ACCESS_TOKEN",
    };
  </script>

  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>

</head>

<body>

  <arcgis-map basemap="arcgis/topographic" center="-118.805, 34.020" zoom="13">
    <arcgis-zoom slot="top-left"></arcgis-zoom>

    <div id="basemapStyles" slot="top-right">
      <calcite-label>
        Basemap Style:
        <calcite-combobox id="styleCombobox" selection-mode="single" clear-disabled></calcite-combobox>
      </calcite-label>
    </div>

  </arcgis-map>

  <script type="module">
    const esriRequest = await $arcgis.import("@arcgis/core/request.js");

  </script>

</body>

</html>

Create a variable for the Map component and the combobox and wait for the view to be ready.

52 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>ArcGIS Maps SDK for JavaScript Tutorials: Change the basemap style</title>
  <style>
    html,
    body {
      height: 100%;
      margin: 0;
    }


    #basemapStyles {
      background-color: white;
      border-radius: 5px;
      padding: 10px;
      width: 250px;
    }


  </style>

  <script>
    var esriConfig = {
      apiKey: "YOUR_ACCESS_TOKEN",
    };
  </script>

  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>

</head>

<body>

  <arcgis-map basemap="arcgis/topographic" center="-118.805, 34.020" zoom="13">
    <arcgis-zoom slot="top-left"></arcgis-zoom>

    <div id="basemapStyles" slot="top-right">
      <calcite-label>
        Basemap Style:
        <calcite-combobox id="styleCombobox" selection-mode="single" clear-disabled></calcite-combobox>
      </calcite-label>
    </div>

  </arcgis-map>

  <script type="module">
    const esriRequest = await $arcgis.import("@arcgis/core/request.js");

    const viewElement = document.querySelector("arcgis-map");
    const styleCombobox = document.querySelector("#styleCombobox");
    // wait for the view to be ready
    await viewElement.viewOnReady();

5 collapsed lines
  </script>

</body>

</html>

Fetch the list of styles available from the /self endpoint for the basemap styles service using the esriRequest method. Specify json as the response type. This will return a json response with a styles property.

57 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>ArcGIS Maps SDK for JavaScript Tutorials: Change the basemap style</title>
  <style>
    html,
    body {
      height: 100%;
      margin: 0;
    }


    #basemapStyles {
      background-color: white;
      border-radius: 5px;
      padding: 10px;
      width: 250px;
    }


  </style>

  <script>
    var esriConfig = {
      apiKey: "YOUR_ACCESS_TOKEN",
    };
  </script>

  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>

</head>

<body>

  <arcgis-map basemap="arcgis/topographic" center="-118.805, 34.020" zoom="13">
    <arcgis-zoom slot="top-left"></arcgis-zoom>

    <div id="basemapStyles" slot="top-right">
      <calcite-label>
        Basemap Style:
        <calcite-combobox id="styleCombobox" selection-mode="single" clear-disabled></calcite-combobox>
      </calcite-label>
    </div>

  </arcgis-map>

  <script type="module">
    const esriRequest = await $arcgis.import("@arcgis/core/request.js");

    const viewElement = document.querySelector("arcgis-map");
    const styleCombobox = document.querySelector("#styleCombobox");
    // wait for the view to be ready
    await viewElement.viewOnReady();

    // update combobox values with styles from rest endpoint
    const basemapStylesEndpoint =
      "https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/self";
    esriRequest(basemapStylesEndpoint, {
      responseType: "json",
    }).then((response) => {
      const json = response.data;
      // add each style as a combobox item
      json.styles.forEach((style) => {

      });
    });
6 collapsed lines

  </script>

</body>

</html>

From the response data, use the JavaScript forEach method to iterate through each of the styles and add each style as a calcite-combobox-item. Set the value to the style path, and the label to the style name. If the style path matches the current basemap, set the item as selected.

57 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>ArcGIS Maps SDK for JavaScript Tutorials: Change the basemap style</title>
  <style>
    html,
    body {
      height: 100%;
      margin: 0;
    }


    #basemapStyles {
      background-color: white;
      border-radius: 5px;
      padding: 10px;
      width: 250px;
    }


  </style>

  <script>
    var esriConfig = {
      apiKey: "YOUR_ACCESS_TOKEN",
    };
  </script>

  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>

</head>

<body>

  <arcgis-map basemap="arcgis/topographic" center="-118.805, 34.020" zoom="13">
    <arcgis-zoom slot="top-left"></arcgis-zoom>

    <div id="basemapStyles" slot="top-right">
      <calcite-label>
        Basemap Style:
        <calcite-combobox id="styleCombobox" selection-mode="single" clear-disabled></calcite-combobox>
      </calcite-label>
    </div>

  </arcgis-map>

  <script type="module">
    const esriRequest = await $arcgis.import("@arcgis/core/request.js");

    const viewElement = document.querySelector("arcgis-map");
    const styleCombobox = document.querySelector("#styleCombobox");
    // wait for the view to be ready
    await viewElement.viewOnReady();

    // update combobox values with styles from rest endpoint
    const basemapStylesEndpoint =
      "https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/self";
    esriRequest(basemapStylesEndpoint, {
      responseType: "json",
    }).then((response) => {
      const json = response.data;
      // add each style as a combobox item
      json.styles.forEach((style) => {

        // if the style is complete and not deprecated, add it to the combobox
        if (style.complete && !style.deprecated) {
          const comboboxItem = document.createElement("calcite-combobox-item");
          comboboxItem.value = style.path;
          comboboxItem.heading = style.name;
          // if the current basemap style is the same as the combobox item, select it
          comboboxItem.selected = viewElement.basemap.style.id === style.path;
          styleCombobox.appendChild(comboboxItem);
        }

      });
    });
6 collapsed lines

  </script>

</body>

</html>

Update the style on user input

Use the calciteComboboxChange event to recognize when the user has selected a new language.

Add an event listener to watch for changes on the combobox. When the combobox value has changed, update the basemap style to the selected item.

80 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>ArcGIS Maps SDK for JavaScript Tutorials: Change the basemap style</title>
  <style>
    html,
    body {
      height: 100%;
      margin: 0;
    }


    #basemapStyles {
      background-color: white;
      border-radius: 5px;
      padding: 10px;
      width: 250px;
    }


  </style>

  <script>
    var esriConfig = {
      apiKey: "YOUR_ACCESS_TOKEN",
    };
  </script>

  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script type="module" src="https://js.arcgis.com/5.0/"></script>

</head>

<body>

  <arcgis-map basemap="arcgis/topographic" center="-118.805, 34.020" zoom="13">
    <arcgis-zoom slot="top-left"></arcgis-zoom>

    <div id="basemapStyles" slot="top-right">
      <calcite-label>
        Basemap Style:
        <calcite-combobox id="styleCombobox" selection-mode="single" clear-disabled></calcite-combobox>
      </calcite-label>
    </div>

  </arcgis-map>

  <script type="module">
    const esriRequest = await $arcgis.import("@arcgis/core/request.js");

    const viewElement = document.querySelector("arcgis-map");
    const styleCombobox = document.querySelector("#styleCombobox");
    // wait for the view to be ready
    await viewElement.viewOnReady();

    // update combobox values with styles from rest endpoint
    const basemapStylesEndpoint =
      "https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/self";
    esriRequest(basemapStylesEndpoint, {
      responseType: "json",
    }).then((response) => {
      const json = response.data;
      // add each style as a combobox item
      json.styles.forEach((style) => {

        // if the style is complete and not deprecated, add it to the combobox
        if (style.complete && !style.deprecated) {
          const comboboxItem = document.createElement("calcite-combobox-item");
          comboboxItem.value = style.path;
          comboboxItem.heading = style.name;
          // if the current basemap style is the same as the combobox item, select it
          comboboxItem.selected = viewElement.basemap.style.id === style.path;
          styleCombobox.appendChild(comboboxItem);
        }

      });
    });

    styleCombobox.addEventListener("calciteComboboxChange", (event) => {
      const basemapId = event.target.value;
      if (basemapId) {
        // update the basemap style
        viewElement.basemap = basemapId;
      }
    });
6 collapsed lines

  </script>

</body>

</html>

Run the App

In CodePen, run your code to display the map.

Use the Calcite combobox in the top right to select and explore different basemap styles from the Basemap styles service (v2).

What’s Next?

Learn how to use additional SDK features and ArcGIS services in these tutorials: