How to Customize Esri Vector Basemaps

Updated December 15, 2016:  The Esri Vector Basemaps are no longer in beta release and are now available to use in production web maps and apps. The best way to access them in ArcGIS Online is through the Esri owned Vector Basemaps group, which contains the latest set of web maps and tile layers. See What’s New in Esri Vector Basemaps (December 2016) for information related to this update.

The information in this blog is updated and now references Beta 2 (B2) Esri vector tile layers released May 13, 2016.  

As described in this post, Esri has introduced an updated set of vector basemaps (now a Beta 2 release).  These vector basemaps offer several benefits (e.g., fast to download, look great on high-res displays, smaller and easier to update, etc), but perhaps the greatest benefit is that users can customize the look and feel of the basemaps.

Users who want to customize the Esri Vector Basemaps can do so by editing the style for one of the existing tile layers (e.g., Light Gray Canvas) and then publishing the updated style as a new tile layer.  Some of the options for customizing the Esri vector basemaps include:

  • Turn layers on or off
  • Change the colors and symbols used for a layer
  • Change between language options available in selected areas
  • Change the representation of disputed boundaries displayed in selected areas

Custom Map Style Example

Below is an example of a custom map that has been created from one of the available Esri vector basemap tile layers.

In this example, the Light Gray Canvas tile layer was updated simply by changing the hex colors for a few layers in the map.

  • Background and water bodies: changed color from ‘#cfcfd4′ to ‘#a6deff’
  • Land and vegetation areas: changed color from ‘#ededed’ to ‘#dfffd9′
  • Urban area: changed color from ‘#e8e8e8′ to ‘#d5e3ca’

Because these layers appear multiple times in the map style for different zoom levels, the changes were made with a batch find and replace to update all of the appropriate layers.

Create a Custom Map

How was this map created?  The steps to create a custom map are pretty simple, though the time and effort involved could vary significantly depending the level of customization desired.  To create a custom vector basemap, you can follow the steps below:

Step 1: Create New Tile Layer Item that You Own

  1. Sign in to ArcGIS Online with your account and click Map.
  2. To add vector tile layer, click the Add button, select Search for Layers in ArcGIS Online, type in ‘esri vector basemap’, and click Go.
  3. Select one of the layers owned by ‘esri_vector’ (such as ‘Light Gray Canvas’) and click Add and then Done Adding Layers.
  4. In the table of contents, hover over the selected layer and click More Options (shown as ‘‘) and select Copy option.
  5. For the layer that you copied, click More Options and select Save Layer option. Update the info and click Create Item button.

Step 2: Update the Style for the New Tile Layer

  1. For the layer that you created, click More Options and select Show Item Details option.
  2. To download the style, click the Open button and select Download style option.  If you’d like to preview the style, select the View style option first.
  3. Open the ‘root.json’ style file that you downloaded in a JSON editor, make a few edits (such as described for example above), and then Save the JSON file (if you like, you can rename the file, such as ‘mymap.json’).
    • While editing a JSON style file may be unfamiliar to some of us, it is a common workflow for many web designers and developers. The Esri vector basemaps are built using the Mapbox vector tile specification (v8).  You can refer to the Mapbox GL Style Reference for info on how to style the data in the tiles.  Additional info on layers in the Esri vector basemaps will be provided separately.
  4. To update your layer with this style, go to the item details page for your tile layer and click the Update button. Choose the file that you saved and click the Update Item button. You have now updated your map style!
  5. To see the changes, click the Open button and select Add layer to new map option. You can continue to make changes to the style file and update the tile layer item until you are done.

Step 3: Create a Map with Your New Tile Layer

  1. Once you are done updating style for the tile layer, you can update the tile layer item details (e.g. create a new thumbnail, edit the item description and other info).
  2. To create a new map with your tile layer, click the Open button and select Add layer to new map option.  Navigate the map to an area of interest and click the Save button.  Enter the requested info and click the Save Map button.
    • If you would like to use your new tile layer as a basemap layer, you can do that also.  In the Map Viewer, click the Add button, select Search for Layers in My Content, find your new tile layer, click on the title of the layer, and select Use as basemap option.
  3. After you save the map, you can update the web map item details (e.g. create a new thumbnail, edit the item description and other info) and then share or use the map as desired.  You can embed in an app or website as usual.

Did you already customize an Esri vector tile layer?

If you customized a root.json style file copied from Esri’s first Beta vector tile layers, released November 2015, your maps will continue to work and display all your customization. However, we have released an updated Beta 2 (B2) version of the tile set, the underlying data, and the basemap styles.  Because of changes in the updates, any customized layers built from the first Beta do not take advantage of any improvements. We recommended you update earlier Beta tile layers with the latest B2 vector tile layers. Any customization will need to be re-applied to the root.json style now associated with this new set of B2 tiles.

More Customization Options

Additional tools and workflows will be available to customize vector basemaps to meet your specific needs.  More information and examples for how to customize map styles will be published soon in separate blog posts, such as below:

We encourage you to give it a try and show us your style!

This entry was posted in ArcGIS Online, Community Maps, Mapping and tagged , , , , , . Bookmark the permalink.

Leave a Reply


  1. esri4591 says:

    Any recommend easy to use JSON viewer for edit “root.json” ?

  2. mvrtich says:

    Any chance to use the new Mapbox Studio to edit the Esri’s Style?

    • Deane Kensok says:

      I’m not sure that will be an option but we’ll check it out. We will also provide some additional tools to edit the styles for users that want to do more sophisticated things.

      • Craig Williams says:

        Mapbox Studio doesn’t allow style editing of tiles hosted outside of Mapbox at this time.

        • mvrtich says:

          Have a look at To edit Esri vector tiles style, you have to edit “sources” attribute in the style definition:
          Before: {"esri":{"type":"vector","url":""}}
          After: {"esri":{"type":"vector","tiles":["{z}/{y}/{x}.pbf"]}}

  3. gis_ta says:

    Would be nice to have a guide or table of contents for where the features are in the style file. For example, city, state, county boundaries in lines 0-100, and transportation lines 101-200, road labels 201-400, etc…. Having this standardized across all the basemaps would be a nice consistent way to help users customize them quickly.

    • Deane Kensok says:

      Thanks for the feedback. We are working on a guide to help understand the contents and structure of the vector tiles. We’ll publish that in the next couple weeks, and update this post to reference it.

      We’ll also share some other example maps soon that illustrate other ways you can customize the maps.

  4. kateleroux says:

    Playing with this is fun, but I have one question: what fonts are available? I tried changing the text-font property of a label and the label just didn’t appear. I tried ones I thought would be basic, like Arial Black. Can you please put up a list of the available fonts in your fontstack?

    • Craig Williams says:

      At this point only Arial Regular, Arial Bold, Arial Italic, Arial Bold Italic are available. There will be more options for font sharing when ArcGIS Pro 1.2 tile creation is released.

  5. thowze says:

    Will these be available for ArcGIS Desktop too?

  6. yanivm says:

    How come in all the Esri vector basemap tile layers
    the Sea of Galile is Connected with the dead see and shown as a huge body of water?
    While in the geology history this picrture probably was right,
    it has nothing to reality of nowdays?

  7. says:

    Will vector basemaps be editable and accessible in ArcDesktop 10.3.1 or 10.4. Or will this just be a ArcGIS Pro advantage?

  8. lebogang01_1 says:

    Regarding your previous comment: “We will support vector tiles (both creation and consumption) in ArcGIS Pro but do not have plans to support in other ArcGIS Desktop apps such as ArcMap.”

    Is there creation of vector based maps availble for ArcGIS Pro 1.2/ Pre – release version? If so, are there any steps for it?

    • Craig Williams says:

      The complete documentation for this did not make the Pre Release cut. If you have access to the Pro 1.2 beta community, you can find a copy of the documentation there.

  9. inteller says:

    cartography (“style editing”) has been visual since the beginning of time. This was a failure with ArcIMS/AXLs back in the day and it is a failure now. Give us a visual tool to modify the cartography of vector tile layers or this will be a failure too.

  10. chad0304 says:

    Is there any way to get the customized vector basemap from ArcGIS Online to ArcMap Desktop?

    • mapguy says:

      Deane wrote: We will support vector tiles (both creation and consumption) in ArcGIS Pro but do not have plans to support in other ArcGIS Desktop apps such as ArcMap.

  11. varvara_t says:

    For the current vector basemaps release a lot has changed, for example there are no ‘name_global’ or ‘name_local’ tags. How should the language be changed now?

  12. linda_n18 says:

    I have been through this process numerous times. Why don’t I see the option: “Download style” after clicking the “Show Item Details”??? I have a tile layer and been through Step 1 more than 5 times. What am I missing?

  13. kirath says:


    I can not find any basemap which is owned by esri_vector. When searching for “light grey canvas” for example, the results only show the normal maps I would also find searching within ArcGIS Online without an ESRI account, and the light grey canvas map would be owned by esri, not by esri_vector. I can therefore not edit the basemap and also not delete the labels, which I would urgently need to do.
    What am I doing wrong?

    Thanks in advance for the help!!

    • Deane Kensok says:

      Hello Kira,

      Now that our vector basemaps are out of beta, the ‘official’ released versions of them are now owned by ‘esri’ account and are accessible in our Vector Basemaps group (see updated note at top of blog for link). If you filter the group to show “Layers” you will see the latest vector tile layers (including Light Gray Canvas). You can always use this group going forward to find the latest Vector Basemap maps and layers.