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.

[iframe width=”100%” height=”400″ frameborder=”0″ scrolling=”no” marginheight=”0″ marginwidth=”0″ title=”Custom Canvas Map” src=”https://www.arcgis.com/apps/Embed/index.html?webmap=53cdb354fa7442b98bc6491495be420a&extent=-129.1409,22.2022,-64.2337,52.998&zoom=true&scale=false&disable_scroll=true&theme=light”]

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.

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:

• Updates to Esri Vector Basemaps Released (Beta 2)
• Customize Esri Vector Basemap Boundaries and Labels
• Understanding Esri Vector Basemap File Structure

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