Change the static basemap tiles style

Learn how to change the static basemap tiles style.

The static basemap tiles service provides access to raster basemap tiles for the world. The service supports a number of ArcGIS styles such as navigation, streets, outdoor, and light-gray. The tiles are returned as PNG files.

In this tutorial, you use the dropdown menu to toggle between the different static basemap tiles.

Prerequisites

Steps

Get the starter app

Select a type of authentication below and follow the steps to create a new application.

Set up authentication

Create developer credentials in your portal for the type of authentication you selected.

Set developer credentials

Use the API key or OAuth developer credentials so your application can access location services.

Add a style selector

1. Create a <div> tag to contain the <select> dropdown menu. Add the supported basemap style enumerations from the static basemap tiles service as <option>s.

   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
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
     <div id="map"></div>
   
     <div id="basemaps-wrapper">
       <select id="basemaps">
         <option value="arcgis/outdoor">arcgis/outdoor</option>
         <option value="arcgis/streets">arcgis/streets</option>
         <option value="arcgis/streets-night">arcgis/streets-night</option>
         <option value="arcgis/navigation">arcgis/navigation</option>
         <option value="arcgis/navigation-night">arcgis/navigation-night</option>
         <option value="arcgis/light-gray">arcgis/light-gray</option>
         <option value="arcgis/dark-gray">arcgis/dark-gray</option>
         <option value="arcgis/imagery/labels">arcgis/imagery/labels</option>
         <option value="arcgis/oceans/labels">arcgis/oceans/labels</option>
         <option value="arcgis/community">arcgis/community</option>
         <option value="arcgis/nova">arcgis/nova</option>
         <option value="arcgis/midcentury">arcgis/midcentury</option>
         <option value="arcgis/newspaper">arcgis/newspaper</option>
         <option value="arcgis/human-geography">arcgis/human-geography</option>
         <option value="arcgis/human-geography-dark">arcgis/human-geography-dark</option>
       </select>
     </div>
   

2. In the <style> element, add CSS styling to the basemaps-wrapper and basemaps.

   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
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
     <style>
       body {
         margin: 0;
         padding: 0;
       }
   
       html,
       body,
       #map {
         height: 100%;
       }
   
   
       #basemaps-wrapper {
         position: absolute;
         top: 20px;
         right: 20px;
         background: rgba(255, 255, 255, 0);
       }
   
       #basemaps {
         font-size: 16px;
         padding: 4px 8px;
       }
   
   
     </style>
   

Update the map's viewpoint

1. Change the map's center to [-91.2996, 37.1174] and zoom level to 4. This will focus the map on the United States of America.

   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
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
       const map = new maplibregl.Map({
         container: 'map',
   
         zoom: 4,
         center: [-91.2996, 37.1174],
   
       });
   

Set the basemap

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

1. Change the basemapEnum to arcgis/outdoor. This will be the default 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
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
       /* Use for API key authentication */
       const accessToken = "YOUR_ACCESS_TOKEN";
   
       // or
   
       /* Use for user authentication */
       // const session = await arcgisRest.ArcGISIdentityManager.beginOAuth2({
       //   clientId: "YOUR_CLIENT_ID", // Your client ID from OAuth credentials
       //   redirectUri: "YOUR_REDIRECT_URI", // The redirect URL registered in your OAuth credentials
       //   portal: "YOUR_PORTAL_URL" // Your portal URL
       // })
   
       // const accessToken = session.token;
   
       const basemapEnum = "arcgis/outdoor";
   
   

   Expand

2. Create a baseUrl and a url variables. 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
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
       /* Use for API key authentication */
       const accessToken = "YOUR_ACCESS_TOKEN";
   
       // or
   
       /* Use for user authentication */
       // const session = await arcgisRest.ArcGISIdentityManager.beginOAuth2({
       //   clientId: "YOUR_CLIENT_ID", // Your client ID from OAuth credentials
       //   redirectUri: "YOUR_REDIRECT_URI", // The redirect URL registered in your OAuth credentials
       //   portal: "YOUR_PORTAL_URL" // Your portal URL
       // })
   
       // const accessToken = session.token;
   
       const basemapEnum = "arcgis/outdoor";
   
       const baseUrl = "https://static-map-tiles-api.arcgis.com/arcgis/rest/services/static-basemap-tiles-service/v1";
       const url = (style) => `${baseUrl}/${style}/static/tile/{z}/{y}/{x}?token=${accessToken}`;
   
   

   Expand

3. Set the style of the map to include a source of raster-tiles and a layer with an id of raster-basemap. Pass basemapEnum inside the tiles attribute as the default 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
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
       /* Use for API key authentication */
       const accessToken = "YOUR_ACCESS_TOKEN";
   
       // or
   
       /* Use for user authentication */
       // const session = await arcgisRest.ArcGISIdentityManager.beginOAuth2({
       //   clientId: "YOUR_CLIENT_ID", // Your client ID from OAuth credentials
       //   redirectUri: "YOUR_REDIRECT_URI", // The redirect URL registered in your OAuth credentials
       //   portal: "YOUR_PORTAL_URL" // Your portal URL
       // })
   
       // const accessToken = session.token;
   
       const basemapEnum = "arcgis/outdoor";
   
       const baseUrl = "https://static-map-tiles-api.arcgis.com/arcgis/rest/services/static-basemap-tiles-service/v1";
       const url = (style) => `${baseUrl}/${style}/static/tile/{z}/{y}/{x}?token=${accessToken}`;
   
       const map = new maplibregl.Map({
         container: 'map',
   
         style: {
           'version': 8,
           'sources': {
             'raster-tiles': {
               'type': 'raster',
               'tiles': [
                 url(basemapEnum)
               ],
               'tileSize': 512,
             },
           },
           'layers': [
             {
               'id': 'raster-basemap',
               'type': 'raster',
               'source': 'raster-tiles',
               'minzoom': 0,
               'maxzoom': 22
             },
           ]
         },
   
         zoom: 4,
         center: [-91.2996, 37.1174],
   
       });
   
   

   Expand

4. Run the code to ensure the map displays the default basemap and 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. 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
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
       const basemapsSelectElement = document.querySelector("#basemaps");
   
   

   Expand

2. Add an event listener to store the selected 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
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
       const basemapsSelectElement = document.querySelector("#basemaps");
   
       basemapsSelectElement.addEventListener("change", (e) => {
         const style = e.target.value;
         const tilesUrl = url(style);
   
       });
   

   Expand

3. Update the map's raster-tiles with the new 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
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
       const basemapsSelectElement = document.querySelector("#basemaps");
   
       basemapsSelectElement.addEventListener("change", (e) => {
         const style = e.target.value;
         const tilesUrl = url(style);
   
         map.getSource('raster-tiles').setTiles([tilesUrl]);
   
       });
   

   Expand

Update attribution

You will update the attribution text for basemap styles service from the previous tutorial to the attribution for static basemap tiles service. You retrieve the data attribution manually from the service URL and display it in the map's attribution control. You also prepend Powered by Esri in the attribution string.

1. Fetch the copyrightText from the service URL. Then, display it and prepend Powered by Esri string in the map's attribution control.

   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
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
       // Add Esri and data attribution
       // Learn more in https://esriurl.com/attribution
       fetch(`${baseUrl}/${basemapEnum}/static?token=${accessToken}`)
         .then(response => response.json())
         .then(data => {
           map._controls[0]._innerContainer.innerText += " | Powered by Esri | " + data.copyrightText;
        });
   

   Expand

Run the app

Run the app.

You should be able to use the select element to switch between basemap styles.

What's next?

Learn how to use additional ArcGIS location services in these tutorials: