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 and OSM 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

  1. 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.

  1. Go to the Create an API key tutorial and create an API key with the following privilege(s):
    • Privileges
      • Location services > Basemaps
  2. In CodePen, set esriConfig.apiKey to your API key..
    Use dark colors for code blocks
    1
    2
    3
    4
    esriConfig.apiKey = "YOUR_ACCESS_TOKEN";
    const map = new Map({
      basemap: "arcgis/topographic" // basemap styles service
    });

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

Create a basemap style function

Create a function that accepts a basemap style id and updates the map to the corresponding basemap style.

  1. Define a new updateBasemapStyle function that accepts a style id and updates the current basemap.
    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
    103
    104
    105
    106
    107
          const updateBasemapStyle = (basemapId) => {
            view.map.basemap = basemapId;
          };
    
    Expand

Add a Calcite combobox to change the basemap style

Reference additional basemap styles you would like to use in your application. Use a Calcite combobox to change the basemap style.

  1. Add references to Calcite components in the <head> tag.

    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
    103
    104
    105
    106
    107
      <script type="module" src="https://js.arcgis.com/calcite-components/2.11.1/calcite.esm.js"></script>
      <link rel="stylesheet" type="text/css" href="https://js.arcgis.com/calcite-components/2.11.1/calcite.css" />
    
    Expand
  2. Create a HTML div element with a calcite label and combobox component with the basemap styles.

    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
    103
    104
    105
    106
    107
      <div id="basemapStyles" class="esri-widget">
        <calcite-label>Basemap style</calcite-label>
        <calcite-combobox id="styleCombobox" selection-mode="single" clear-disabled>
          <calcite-combobox-item value="arcgis/navigation" text-label="arcgis/navigation"></calcite-combobox-item>
          <calcite-combobox-item value="arcgis/navigation-night" text-label="arcgis/navigation-night"></calcite-combobox-item>
          <calcite-combobox-item value="arcgis/streets" text-label="arcgis/streets"></calcite-combobox-item>
          <calcite-combobox-item value="arcgis/streets-relief" text-label="arcgis/streets-relief"></calcite-combobox-item>
          <calcite-combobox-item value="arcgis/streets-night" text-label="arcgis/streets-night"></calcite-combobox-item>
          <calcite-combobox-item value="arcgis/outdoor" text-label="arcgis/outdoor"></calcite-combobox-item>
          <calcite-combobox-item value="arcgis/imagery" text-label="arcgis/imagery"></calcite-combobox-item>
          <calcite-combobox-item value="arcgis/topographic" text-label="arcgis/topographic" selected></calcite-combobox-item>
          <calcite-combobox-item value="arcgis/terrain" text-label="arcgis/terrain"></calcite-combobox-item>
          <calcite-combobox-item value="arcgis/oceans" text-label="arcgis/oceans"></calcite-combobox-item>
          <calcite-combobox-item value="arcgis/light-gray" text-label="arcgis/light-gray"></calcite-combobox-item>
          <calcite-combobox-item value="arcgis/dark-gray" text-label="arcgis/dark-gray"></calcite-combobox-item>
          <calcite-combobox-item value="arcgis/human-geography" text-label="arcgis/human-geography"></calcite-combobox-item>
          <calcite-combobox-item value="arcgis/human-geography-dark" text-label="arcgis/human-geography-dark"></calcite-combobox-item>
          <calcite-combobox-item value="arcgis/charted-territory" text-label="arcgis/charted-territory"></calcite-combobox-item>
          <calcite-combobox-item value="arcgis/colored-pencil" text-label="arcgis/colored-pencil"></calcite-combobox-item>
          <calcite-combobox-item value="arcgis/nova" text-label="arcgis/nova"></calcite-combobox-item>
          <calcite-combobox-item value="arcgis/modern-antique" text-label="arcgis/modern-antique"></calcite-combobox-item>
          <calcite-combobox-item value="arcgis/midcentury" text-label="arcgis/midcentury"></calcite-combobox-item>
          <calcite-combobox-item value="arcgis/newspaper" text-label="arcgis/newspaper"></calcite-combobox-item>
          <calcite-combobox-item value="osm/standard" text-label="osm/standard"></calcite-combobox-item>
          <calcite-combobox-item value="osm/standard-relief" text-label="osm/standard-relief"></calcite-combobox-item>
          <calcite-combobox-item value="osm/navigation" text-label="osm/navigation"></calcite-combobox-item>
          <calcite-combobox-item value="osm/navigation-dark" text-label="osm/navigation-dark"></calcite-combobox-item>
          <calcite-combobox-item value="osm/streets" text-label="osm/streets"></calcite-combobox-item>
          <calcite-combobox-item value="osm/hybrid" text-label="osm/hybrid"></calcite-combobox-item>
          <calcite-combobox-item value="osm/light-gray" text-label="osm/light-gray"></calcite-combobox-item>
          <calcite-combobox-item value="osm/dark-gray" text-label="osm/dark-gray"></calcite-combobox-item>
          <calcite-combobox-item value="osm/blueprint" text-label="osm/blueprint"></calcite-combobox-item>
        </calcite-combobox>
      </div>
    
    Expand
  3. Add the basemapStyles div to the view UI.

    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
    103
    104
    105
    106
    107
          const basemapStylesDiv = document.getElementById("basemapStyles");
          view.ui.add(basemapStylesDiv, "top-right");
    
    
    Expand
  4. Apply some CSS styling to the basemapStyles div within the <style> tags.

    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
    103
    104
    105
    106
    107
        #basemapStyles {
          width: 250px;
          padding: 10px;
        }
    
    Expand
  5. Add an event listener to watch for changes on the combobox. When the combobox value has changed, call the updateBasemapStyle function to update the basemap style.

    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
    103
    104
    105
    106
    107
          const basemapStylesDiv = document.getElementById("basemapStyles");
          view.ui.add(basemapStylesDiv, "top-right");
    
          const styleCombobox = document.getElementById("styleCombobox");
          styleCombobox.addEventListener("calciteComboboxChange", (event) => {
            updateBasemapStyle(event.target.value);
          });
    
    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:

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.