Basemap styles

Custom basemap style created from the Nova style with the Vector Tile Style Editor

What is a basemap style?

A basemap style is a set of visual properties that define how the geographic features and labels from the basemap styles service are displayed. The format of a basemap style conforms to the Mapbox Style Specification for vector tile layers. The basemap styles service supports default basemap styles and custom basemap styles. Default basemap styles are predefined styles, also known as themes, that are included with the service such as streets, navigation, light gray, and imagery.

What is a custom basemap style?

A custom basemap style is a unique basemap style that you can create for the basemap styles service. A custom basemap style is derived from a default basemap style and is created with the ArcGIS Vector Tile Style Editor. The editor allows you to customize the style properties of geographic features and labels such as visibility, fill colors, outline colors, fonts, and glyphs. The format of a custom basemap style conforms to the Mapbox Style Specification for vector tile layers.

You use a custom basemap style to:

  • Create your own unique basemap color scheme for a mapping application.
  • Emphasize or de-emphasize geographic features and labels in the default basemap styles.
  • Match geographic features and labels to a specific set of branding colors or fonts.
  • Create new styles that can be shared with others.

How to use a custom basemap style

The typical workflow to create and use a custom basemap style is:

1. Create a new style

To create a new custom basemap style, you use the ArcGIS Vector Tile Style Editor. You start by selecting one of the default basemap styles such as arcgis/streets, arcgis/topographic, arcgis/navigation, or osm/standard. The editor copies the existing style and then allows you to start editing the new style. The editor provides a number of tools that let you inspect and set the visual properties for all of the features and labels in each layer. The most common layer properties you edit in the style are the following:

  • Visibility
  • Visible zoom range
  • Fill color
  • Outline color
  • Opacity
  • Size and font type for labels
  • Swatches
  • Glyphs

The general steps to create a style are:

  1. Sign in to your ArcGIS.com or ArcGIS Enterprise portal and go to ArcGIS Vector Tile Style Editor.
  2. Select a default basemap style.
  3. Start editing the visual properties for each layer in the style.
ArcGIS Vector Tile Style Editor
Example of using ArcGIS Vector Tile Style Editor to create a custom basemap style.

2. Manage the style

When you are finished editing the new basemap style, you need to save the style with the ArcGIS Vector Tile Style Editor. The new style is saved in ArcGIS as a vector tile layer (item) in the portal you are signed in to. From the item page, you can display the style with Map Viewer or Scene Viewer. You can also use this page to set the sharing level, view the style, update the JSON, or get the URL endpoint.

After the style is saved, there are two tools you can use to manage it:

  1. ArcGIS Vector Tile Style Editor: Use the editor to share and edit style; or,
  2. Item page: Use the item to set the properties and sharing level. You can also use this page to view the JSON for the style.

Below is an example of an item for a custom basemap style:

ArcGIS Vector Tile Style Editor
Example of a vector tile layer item page for a custom basemap style.

3. Access the style

To display a custom basemap style in a map or scene, you need to reference the item by item ID or service URL. To access the JSON directly, you use the service URL with /root.json.

To access the JSON for a basemap style:

  1. Go to ArcGIS.com or ArcGIS Enterprise portal.
  2. Find the style item (tile layer).
  3. Use the item ID or the service URL to access the style.
  4. Display the style as vector tile layer in a basemap.

Below is an example of an item and service URL for a style:

ArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for .NETArcGIS Maps SDK for KotlinArcGIS Maps SDK for JavaArcGIS Maps SDK for SwiftArcGIS Maps SDK for Qt (C++)MapLibre GL JSOpenLayersEsri Leaflet
Expand
Use dark colors for code blocksCopy
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
        esriConfig.apiKey = "YOUR_API_KEY";

        const basemap = new Basemap({
          baseLayers: [
            new VectorTileLayer({
              portalItem: {
                id: "692f461ceb2f4d598aaf8d2837b859da" // Custom basemap style
              }
            })
          ]
        });

        const map = new Map({
          basemap: basemap
        });

Style format

The item for a custom basemap style contains the visual properties stored as JSON that follows the Mapbox Style Specification. The style JSON contains drawing resources and properties such as the glyphs, version, sprite, sources, and layers.

Each layer in the style contains the visual properties for the features in the vector tile layer such as land areas, oceans, lakes, parks, streets, and place labels. Some of the key properties are id, type, and paint. The paint property contains the values used by a client application to display the layer, including the color and color ranges.

Below is an example of the JSON:

Use dark colors for code blocksCopy
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
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
{
  "glyphs": "https://basemaps-api.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/resources/fonts/{fontstack}/{range}.pbf",
  "version": 8,
  "sprite": "https://www.arcgis.com/sharing/rest/content/items/d2ff12395aeb45998c1b154e25d680e5/resources/styles/sprite-1551462317894",
  "sources": {
    "esri": {
      "url": "https://basemaps-api.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer",
      "type": "vector"
    }
  },
  "layers": [
    {
      "paint": {
        "background-opacity": 0,
        "background-color": "#c9def0",
        "text-color": "#828282",
        "text-halo-color": "#fbfbfb"
      },
      "type": "background",
      "id": "background",
      "layout": {
        "visibility": "none"
      },
      "showProperties": false
    },
    {
      "layout": {},
      "paint": {
        "fill-color": "#fbf8f3",
        "text-color": "#828282",
        "text-halo-color": "#fbfbfb"
      },
      "source": "esri",
      "source-layer": "Land",
      "type": "fill",
      "id": "Land"
    },
    {
      "layout": {
        "visibility": "none"
      },
      "paint": {
        "fill-color": "#f4ede2",
        "text-color": "#828282",
        "text-halo-color": "#fbfbfb"
      },
      "source": "esri",
      "minzoom": 5,
      "source-layer": "Urban area",
      "maxzoom": 15,
      "type": "fill",
      "id": "Urban area",
      "showProperties": false
    },
    {
      "layout": {},
      "paint": {
        "fill-outline-color": "#abc98e",
        "fill-color": "#b7d29d",
        "text-color": "#828282",
        "text-halo-color": "#fbfbfb"
      },
      "source": "esri",
      "minzoom": 12,
      "source-layer": "Openspace or forest",
      "type": "fill",
      "id": "Openspace or forest",
      "showProperties": false
    },
    {
      "layout": {},
      "paint": {
        "fill-opacity": 0.6,
        "fill-color": {
          "base": 1,
          "stops": [
            [
              3,
              "#ddf0ca"
            ],
            [
              6,
              "#cbe5b1"
            ],
            [
              10,
              "#bae291"
            ]
          ]
        },
        "fill-outline-color": "#bbd4a2"
      },
      "source": "esri",
      "minzoom": 3,
      "source-layer": "Admin0 forest or park",
      "type": "fill",
      "id": "Admin0 forest or park",
      "showProperties": false
    },
    .../ 20240111173702
    // https://www.arcgis.com/sharing/rest/content/items/692f461ceb2f4d598aaf8d2837b859da/resources/styles/root.json

    {
      "version": 8,
      "sprite": "https://www.arcgis.com/sharing/rest/content/items/692f461ceb2f4d598aaf8d2837b859da/resources/sprites/sprite-1701462883165",
      "glyphs": "https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/resources/fonts/{fontstack}/{range}.pbf",
      "sources": {
        "esri": {
          "type": "vector",
          "url": "https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer",
          "tiles": [
            "https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/tile/{z}/{y}/{x}.pbf"
          ]
        }
      },
      "layers": [
        {
          "id": "background",
          "type": "background",
          "paint": {
            "background-color": "#5215ff"
          },
          "layout": {

          }
        },
        {
          "id": "Land",
          "type": "fill",
          "source": "esri",
          "source-layer": "Land",
          "filter": [
            "in",
            "_symbol",
            0,
            1
          ],
          "layout": {

          },
          "paint": {
            "fill-color": "#efb1ff",
            "fill-opacity": 1
          }
        },
        {
          "id": "Urban area",
          "type": "fill",
          "source": "esri",
          "source-layer": "Urban area",
          "minzoom": 5,
          "maxzoom": 15,
          "layout": {

          },
          "paint": {
            "fill-color": "#e7a5f9"
          }
        },
        {
          "id": "Openspace or forest",
          "type": "fill",
          "source": "esri",
          "source-layer": "Openspace or forest",
          "minzoom": 12,
          "layout": {

          },
          "paint": {
            "fill-color": "#7308f3",
            "fill-outline-color": "#6600ee"
          }
        },
        {
          "id": "Admin0 forest or park",
          "type": "fill",
          "source": "esri",
          "source-layer": "Admin0 forest or park",
          "minzoom": 7,
          "layout": {

          },
          "paint": {
            "fill-color": "#7f22f9",
            "fill-outline-color": "#7308f3"
          }
        },
        {
          "id": "Admin1 forest or park",
          "type": "fill",
          "source": "esri",
          "source-layer": "Admin1 forest or park",
          "minzoom": 8,
          "layout": {

          },
          "paint": {
            "fill-color": "#7f22f9",
            "fill-outline-color": "#7308f3"
          }
        },
        {
          "id": "Zoo",
          "type": "fill",
          "source": "esri",
          "source-layer": "Zoo",
          "minzoom": 12,
          "layout": {

          },
          "paint": {
            "fill-color": "#7308f3"
          }
        },
        {
          "id": "Airport/Airport property",
          "type": "fill",
          "source": "esri",
          "source-layer": "Airport",
          "filter": [
            "==",
            "_symbol",
            1
          ],
          "minzoom": 9,
          "layout": {

          },
          "paint": {
            "fill-color": "#d590e8"
          }
        },
        {
          "id": "Airport/Airport runway",
          "type": "fill",
          "source": "esri",
          "source-layer": "Airport",
          "filter": [
            "==",
            "_symbol",
            0
          ],
          "minzoom": 11,
          "layout": {

          },
          "paint": {
            "fill-color": "#d590e8"
          }
        },
        {
          "id": "Pedestrian",
          "type": "fill",
          "source": "esri",
          "source-layer": "Pedestrian",
          "minzoom": 14,
          "layout": {

          },
          "paint": {
            "fill-color": "#ec8cff"
          }
        },
        {
          "id": "Park or farming",
          "type": "fill",
          "source": "esri",
          "source-layer": "Park or farming",
          "minzoom": 12,
          "layout": {

          },
          "paint": {
            "fill-color": "#7308f3"
          }
        },
        {
          "id": "Beach",
          "type": "fill",
          "source": "esri",
          "source-layer": "Beach",
          "minzoom": 13,
          "layout": {

          },
          "paint": {
            "fill-pattern": "Special area of interest/Sand"
          }
        },
    ...

Code examples

Create and display a custom basemap style

This example shows you how to create a custom basemap style with ArcGIS Vector Tile Style Editor and display it in an application. You use the editor to copy the default light gray canvas style and then customize it. When the custom basemap style is loaded by the application, it should look the same as the style created with ArcGIS Vector Tile Style Editor. Since the item sharing level is set to everyone (public), the application does not need to use an access token to access the style.

Create

  1. Sign in to ArcGIS.com and go to ArcGIS Vector Tile Style Editor.
  2. Click New style > Light gray canvas.
  3. In the editor, click Randomize to set the colors or use the other tools to set the colors, labels, zoom levels, and other properties for each layer.

Manage

  1. In ArcGIS Vector Tile Style Editor, click Save as.
  2. Set the title, tags, and folder.
  3. Set Share with > Everyone (public) to make it easy to access.

Access

  1. Find the item ID (created above) or use 692f461ceb2f4d598aaf8d2837b859da.
  2. Write code to create a map and access the item.
  3. Display the style as vector tile layer in a basemap.
ArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for .NETArcGIS Maps SDK for JavaArcGIS Maps SDK for KotlinArcGIS Maps SDK for SwiftArcGIS Maps SDK for Qt (C++)MapLibre GL JSOpenLayersEsri Leaflet
Expand
Use dark colors for code blocksCopy
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
        esriConfig.apiKey = "YOUR_API_KEY";

        const basemap = new Basemap({
          baseLayers: [
            new VectorTileLayer({
              portalItem: {
                id: "692f461ceb2f4d598aaf8d2837b859da" // Custom basemap style
              }
            })
          ]
        });

        const map = new Map({
          basemap: basemap
        });

Tutorials

Services

API support

Basemap stylesPoint, line, and polygon stylesData-driven visualization3D visualization
ArcGIS Maps SDK for JavaScript
ArcGIS Maps SDK for Kotlin
ArcGIS Maps SDK for Swift
ArcGIS Maps SDK for Java
ArcGIS Maps SDK for .NET
ArcGIS Maps SDK for Qt
ArcGIS API for Python12
Full supportPartial supportNo support
  • 1. Define renderers with JavaScript.
  • 2. Supports web scenes only.

Tools

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