Change the basemap style

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 esriConfig.apiKey to your access token.

Use dark colors for code blocks
  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.
Expand
Use dark colors for code blocks
```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
    <script type="module">
      const esriRequest = await $arcgis.import("@arcgis/core/request.js");

    </script>
```
Expand

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.

Add an arcgis-placement component to the map to place the content in the top-right of the map component.

Expand
Use dark colors for code blocks
    <arcgis-map basemap="arcgis/topographic" center="-118.805, 34.027" zoom="13">
      <arcgis-zoom position="top-left"></arcgis-zoom>

      <arcgis-placement position="top-right">

      </arcgis-placement>

    </arcgis-map>
Expand

Inside the arcgis-placement component, create a div called basemapStyles with a calcite-combobox component. 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.

Expand
Use dark colors for code blocks
    <arcgis-map basemap="arcgis/topographic" center="-118.805, 34.027" zoom="13">
      <arcgis-zoom position="top-left"></arcgis-zoom>

      <arcgis-placement position="top-right">

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

      </arcgis-placement>

    </arcgis-map>
Expand

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

Expand
Use dark colors for code blocks
      #basemapStyles {
        background-color: white;
        border-radius: 5px;
        padding: 10px;
        width: 250px;
      }
Expand

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

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

Expand

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.

Expand
Use dark colors for code blocks
      // 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) => {

        });
      });
Expand

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.

Expand
Use dark colors for code blocks
      // 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);
          }

        });
      });
Expand

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.

Expand
Use dark colors for code blocks
      styleCombobox.addEventListener("calciteComboboxChange", (event) => {
        const basemapId = event.target.value;
        if (basemapId) {
          // update the basemap style
          viewElement.basemap = basemapId;
        }
      });
Expand

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 API features and ArcGIS services in these tutorials: