Change the basemap style

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

The basemap styles service provides a number basemap layer styles such as topography, streets, outdoor, navigation, and imagery that you can use in maps.

In this tutorial, you use a <select> dropdown menu to toggle between a number of different basemap layer styles.

Prerequisites

You need an ArcGIS Location Platform or ArcGIS Online account.

Steps

Create a new pen

  1. To get started, you can complete the Display a map tutorial or use the .

Get an access token

You need an access token with the correct privileges to access the resources 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. Copy the API key access token to your clipboard when prompted.

  3. In CodePen, update the accessToken variable to use your access token.

    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
    const accessToken = "YOUR_ACCESS_TOKEN";
    const basemapEnum = "arcgis/outdoor";
    const map = new maplibregl.Map({
      container: "map", // the id of the div element
      style: `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/${basemapEnum}?token=${accessToken}`,
      zoom: 12, // starting zoom
      center: [-118.805, 34.027] // starting location [longitude, latitude]
    });
    
  4. Run the code to ensure the basemap is displayed in the map.

To learn about the other types of authentication available, go to Types of authentication.

Add a selector

  1. Create a <div> tag to contain the <select> dropdown menu. Add basemap layer enumerations from the v2 basemap styles service as <option>s.

    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
        </style>
        <script src=https://unpkg.com/maplibre-gl@4/dist/maplibre-gl.js></script>
        <link href=https://unpkg.com/maplibre-gl@4/dist/maplibre-gl.css rel="stylesheet" />
    
      </head>
    
      <body>
        <div id="map"></div>
    
        <div id="basemaps-wrapper">
    
          <select id="basemaps">
            <option value="arcgis/outdoor">arcgis/outdoor</option>
            <option value="arcgis/community">arcgis/community</option>
            <option value="arcgis/navigation">arcgis/navigation</option>
            <option value="arcgis/streets">arcgis/streets</option>
            <option value="arcgis/streets-relief">arcgis/streets-relief</option>
            <option value="arcgis/imagery">arcgis/imagery</option>
            <option value="arcgis/oceans">arcgis/oceans</option>
            <option value="arcgis/topographic">arcgis/topographic</option>
            <option value="arcgis/light-gray">arcgis/light-gray</option>
            <option value="arcgis/dark-gray">arcgis/dark-gray</option>
            <option value="arcgis/human-geography">arcgis/human-geography</option>
            <option value="arcgis/charted-territory">arcgis/charted-territory</option>
            <option value="arcgis/nova">arcgis/nova</option>
            <option value="osm/standard">osm/standard</option>
            <option value="osm/navigation">osm/navigation</option>
            <option value="osm/streets">osm/streets</option>
            <option value="osm/blueprint">osm/blueprint</option>
          </select>
    
        </div>
    
    Expand
  2. In the <style> element, add CSS styling to the basemaps-wrapper and basemaps.

    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
        <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>
        <script src=https://unpkg.com/maplibre-gl@4/dist/maplibre-gl.js></script>
        <link href=https://unpkg.com/maplibre-gl@4/dist/maplibre-gl.css rel="stylesheet" />
    
    Expand

Set the basemap

Use a function to reference the basemap styles service and a style enumeration to update the map. This will be used when a selection is made.

  1. Create a baseUrl and a url element. The url element will append the name of the basemap selected from the dropdown menu.

    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
        <script>
    
          const accessToken = "YOUR_ACCESS_TOKEN";
    
          const basemapEnum = "arcgis/outdoor";
          const map = new maplibregl.Map({
            container: "map", // the id of the div element
            style: `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/${basemapEnum}?token=${accessToken}`,
            zoom: 12, // starting zoom
            center: [-118.805, 34.027] // starting location [longitude, latitude]
          })
    
          const baseUrl = "https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles";
          const url = (style) => `${baseUrl}/${style}?token=${accessToken}`;
    
    Expand
  2. Set the style of the map with the new basemap layer.

    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
          const baseUrl = "https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles";
          const url = (style) => `${baseUrl}/${style}?token=${accessToken}`;
    
          const setBasemap = (style) => {
            // Instantiate the given basemap layer.
            map.setStyle(url(style));
          };
    
    Expand
  3. Run the code to ensure that the <select> element contains different basemap enumerations.

Add an event listener

Use an event listener to register a basemap change in the <select> element and to update the map.

  1. Set the default basemap to arcgis/outdoor.

    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
          const setBasemap = (style) => {
            // Instantiate the given basemap layer.
            map.setStyle(url(style));
          };
    
          setBasemap("arcgis/outdoor");
    
    Expand
  2. Create a basemapsSelectElement to return the basemap from the selector.

    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
          setBasemap("arcgis/outdoor");
    
          const basemapsSelectElement = document.querySelector("#basemaps");
    
    Expand
  3. Add an event listener to update the map to the new basemap when the selector is changed.

    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
          const basemapsSelectElement = document.querySelector("#basemaps");
    
          basemapsSelectElement.addEventListener("change", (e) => {
            setBasemap(e.target.value);
          });
    
    Expand

Run the app

In CodePen, run your code to display the map.

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 ArcGIS location 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.