Basemap styles

Nova basemap layer style displayed, widget with all of the vector tile layer 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:

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:

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",
      "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
    },
    ...

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.

Examples

Find a style ID and URL

All custom styles are stored in ArcGIS as items. You need to know the item ID in order to use the style in an application.

There are two ways to find a style ID:

  1. Your custom styles: Go to your developer dashboard, or view your content in ArcGIS Online.

  2. Public custom styles: Search ArcGIS Online for styles published by other users.

Example: Style item for the Forest and Parks Canvas custom style.

Create a custom basemap style

To create a custom style, use the ArcGIS Vector Tile Style Editor.

  1. Sign in into your developer dashboard.
  2. Click on New basemap style to launch the Vector tile style editor.
  3. Select an existing basemap style to start from.
  4. Set the colors, labels, zoom levels, and other properties for each layer.
  5. Save the style as an item.

ArcGIS Vector Tile Style Editor

Display a custom basemap style

To access and display a custom style in a map or scene, you use the ID or the JSON URL and add the style as a layer. In most cases, it is added as a basemap layer.

This example references the Forest and Parks Canvas custom style.

  1. Find the style's item ID in your dashboard or in ArcGIS Online.
  2. Access the style with the ID or JSON URL.
  3. Add the layer to a map or scene.
ArcGIS JS APIMapbox GL JSOpenLayersEsri LeafletArcGIS .NET APIArcGIS Android APIArcGIS iOS APIArcGIS Java APIArcGIS Qt API (C++)ArcGIS Qt API (QML)
                                                                
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
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no">
  <title>ArcGIS API for JavaScript Tutorials: Add a styled basemap layer</title>
  <style>
    html, body, #viewDiv {
      padding: 0;
      margin: 0;
      height: 100%;
      width: 100%;
  </style>

  <link rel="stylesheet" href="https://js.arcgis.com/4.18//esri/themes/light/main.css" />
  <script src="https://js.arcgis.com/4.18//"></script>

  <script>
    require([
        "esri/config",
        "esri/Map",
        "esri/views/MapView",
        "esri/Basemap",
        "esri/layers/VectorTileLayer"
      ], function(esriConfig,Map, MapView, Basemap, VectorTileLayer) {
        esriConfig.apiKey = "YOUR-API-KEY";

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

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

        var view = new MapView({
          container: "viewDiv",
          map: map,
          center: [-104,35],
          zoom: 4,
          constraints: {
            snapToZoom: false
    </script>
  </head>

  <body>
    <div id="viewDiv"></div>
  </body>
</html>

Tutorials

Services

Basemap layer service

Access streets, satellite, and other basemap styles for maps and scenes.

API support

Point, line, and polygon stylesData-driven visualization3D visualization
ArcGIS API for JavaScriptFully supportedFully supportedFully supported
ArcGIS Runtime API for AndroidFully supportedFully supportedFully supported
ArcGIS Runtime API for iOSFully supportedFully supportedFully supported
ArcGIS Runtime API for JavaFully supportedFully supportedFully supported
ArcGIS Runtime API for .NETFully supportedFully supportedFully supported
ArcGIS Runtime API for QtFully supportedFully supportedFully supported
ArcGIS API for PythonFully supportedDefine renderers with JavaScriptSupports web scenes only
Full supportPartial support (see notes)Not supported

Tools

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