Change the basemap style | ArcGIS Maps SDK for JavaScript

Learn how to change the basemap style in a map using the Basemap styles service .

The basemap styles service 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 .

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 with the correct privileges to access the location services used in this tutorial.

Go to the Create an API key tutorial and create an API key with the following privilege(s) :
- 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 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: