ArcGIS Online

Customizing Esri Vector Basemaps: The Basics revisited

This is an update of a blog and a sequence of story maps written in 2017 looking at the mechanics of customizing our vector basemaps. It includes updated links, and details on working with the ArcGIS Vector Tile Style Editor, now available directly from your tile layer.

If you prefer to go straight to the Story maps, this link takes you to the first of them: Pt 1: The Basics


Vector Tile Layers can be used to create multi-scale maps that are efficient, high-resolution and customizable, and this includes Vector Basemaps. Esri’s Living Atlas Content Team has created vector tile versions of most of our traditional basemaps (plus some new ones), and these work well in themselves …

But have you ever had that moment where you thought ‘This basemap would work really well, if only …’?

Now, with Esri’s Vector Basemaps and our editing apps,you can do something about that!

What are Vector Basemaps?

Our vector basemaps originate as a Vector Tile Package, built in and generated by ArcGIS Pro, then published with a generic style. It establishes the maximum level of content available and a defined scale range for each layer of information. Separate style documents are created in JSON Code for each of our basemaps, although they do not necessarily use all of this content, or the available scale range.

The Vector Tile Package

A vector tile package contains the vector tiles, and various formatting documents. Of interest to us is the Resources Folder, which includes:


Fonts – Any font that is used in the ArcGIS Pro map.

Sprites – PNG Raster images created for special effects, such as textured patterns and point symbols. In some circumstances, once these have been exported from Pro, they are not editable. However, we have created alternatives for our different core maps.

Styles – A root.json file that establishes the symbolization of the map detail. This is editable, and it is the key to the discussion here. We can make changes to this code to affect color, line weight, label size/font, and scale range … either directly, or through an editing app.

How do I work with them?

The Vector Basemaps Reference Document, is a downloadable PDF describing how our maps are structured. As the maps themselves have become more versatile (and we are trying to improve them all the time), our layer structure has become more complex. This document will help you to find your way through. It may be a little confusing at first, but the more you work with it, the more it will make sense. Don’t feel you have to learn it before you start work though (It’s a ‘reference’ document!).

We provide two editing apps to help you on your way. Both require you to sign-in to an organization.

The ArcGIS Vector Tile Style Editor is an intuitive app that leads you through most of the changes you can make to the map style. For most tasks this will make life much easier for you. It can be accessed through the ‘change style’ option in your basemap tile layer or directly online here. As of 2019, it can be used to add and adjust sprites.

The JSON Code Editor is a beta app that has been available for a while. It pairs the JSON style with a preview map as an easy way for you to work directly with the code and see the results. If you are confident in your ability to work with code, the JSON style file gives you access to some more sophisticated options. It cannot be used for adding and adjusting sprites, but it is a requirement if you want to add data layers to the style. You can access it here.

For more information, these links take you to the sequence of story maps. Use these to get a better understanding of how our basemaps are structured, and how to exploit them using these two apps:

Pt 1: The Basics

Pt 2: Colors

Pt 3: Lines

Pt 4: Labels

Pt 5: Sprites



Personalize your maps with vector basemaps

Ready to take your maps to the next level? Vector tiles enable dynamic cartography and provide the flexibility to create your own basemap style. In our September 6, 2018 webinar, we showed you how to use the new ArcGIS Vector Tile Style Editor to personalize your maps, and walked you through an inspiring gallery of creative map styles that incorporate new map features and labels.

You can find a recording of the Webinair here.


About the author

Andy is a Cartographic Designer who has been working with Esri in Redlands for 12 years, most recently on the creation of some of Esri's vector basemaps, and the development of color ramps for ArcGIS Online. Prior to Esri, he was Manager of Cartographic Design at Rand McNally, and before that a Senior Cartographer at GeoSystems/MapQuest. He is originally from England, and worked for a number of years at what is now the University of Derby before moving to the USA. Andy can be contacted at:

Next Article

Map in a minute: Map volcanic activity using ArcGIS Online and ArcGIS Living Atlas

Read this article