Basemap styles

What are basemap styles?

A basemap style, also referred to as a basemap layer style, is a set of visual properties such as fill colors, viewing levels, and fonts that define how the visual elements in a vector tile basemap layer are displayed. You use a basemap style to create a specific type of visualization for the entire extent of a map or scene.

There are two types of basemap styles:

• Default styles: Styles provided by Esri such as Streets, Topographic, Light Gray Canvas, OSM, Mid-Century, and Nova.

• Custom styles: Styles that you create with the ArcGIS Vector Tile Style Editor.

This section covers how to use custom basemap styles in your applications.

How a custom basemap style works

A custom basemap style is created using the Vector tile style editor and is stored in ArcGIS as an item. Each item has a unique ID and contains JSON defining the visual properties for the style. You use an item ID to access and display the style in a map or scene.

The typical workflow for using a custom basemap style is:

1. Create a new custom style from a default style or other custom style.
2. Find the style item and ID for the custom style.
3. Use the ID to display the custom basemap.

Style items

A custom basemap style is stored as a tile layer item in ArcGIS. The source for the item is a vector tile service (this is the same vector tile service used by the default basemap styles, which means that custom styles can include all the same basemap content as the default styles). Each item page contains the name, description, and ID for the custom style. From the item page, you can access and view the style with Map Viewer or Scene Viewer.

This is an example of the item for a custom Forest and Parks basemap style:

• Item page URL: https://www.arcgis.com/home/item.html?id=d2ff12395aeb45998c1b154e25d680e5

• Item ID: d2ff12395aeb45998c1b154e25d680e5.

Style JSON

The item for each style contains a reference to the definition stored as JSON. The JSON contains references to the sprites, glyphs, and the drawing properties for each layer, as well as the underlying tile service or services. The JSON structure follows the Mapbox Style Specification.

Each layer in a style defines the visual properties for each type of feature 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.

You can view the style JSON by accessing the root.json resource for the item. For example, the URL for the Navigation style is:

https://www.arcgis.com/sharing/rest/content/items/d2ff12395aeb45998c1b154e25d680e5/resources/styles/root.json

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
{
  "glyphs": "https://basemaps.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.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",

ArcGIS Vector Tile Style Editor

To create a custom basemap style for your application, you use the ArcGIS Vector Tile Style Editor. Start by selecting a default basemap style or existing custom basemap style, and then use the editor's tools to change the visual properties of each layer. The editor contains a number of tools and UI controls that let you inspect and set the visual properties for each layer.

The most common layer properties are the:

• Fill color
• Opacity
• Visibility level
• Size and font type for labels
• Swatches
• Glyphs

Once you have finished creating a style, use the editor to save it to ArcGIS Online as a new tile layer item with a unique ID.

You use the item's unique ID to access and display the style in applications.

Code examples

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
        esriConfig.apiKey = "YOUR_API_KEY";

        const basemap = new Basemap({
          baseLayers: [
            new VectorTileLayer({
              portalItem: {
                id: "6976148c11bd497d8624206f9ee03e30" // Forest and Parks Canvas style
              }
            })
          ]
        });

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

Tutorials

Create a custom basemap style

Use the Vector tile style editor to style a vector tile basemap layer.

Vector tile style editor 

Display a custom basemap style

Add and display a styled vector tile basemap layer.

JavaScript Esri Leaflet MapLibre OpenLayers 

Services

API support

Tools