Updating an Esri Basemap Vector Tile Package with a Custom Style

Esri has curated a collection of basemaps and has made them available in the various components of the ArcGIS Platform. These basemaps are optimized for use in ArcGIS apps and ready to serve as the perfect backdrop to your operational data. Whatever your chosen Esri basemap, you can package it to take offline for use in an ArcGIS app on your mobile device. To take a vector basemap offline, you can create a Vector Tile Package (.vtpk) for your area of interest in ArcGIS Pro. See Esri documentation for creating a vector tile package: Take a map offline or Create Vector Tile Package.

However, once the .vtpk file is packaged the style that is displayed reverts back to the Streets map style. Luckily there is a workaround to change the style applied to the vector tile package, which can be the style of your intended ArcGIS basemap style or even a custom one that you define. Here’s how you do it:

Obtain the correct style

1. Find your desired basemap style in the Esri Vector Basemaps (for Export) Gallery
   
2. Select the desired basemap layer by clicking on the name to open the Item Details page
3. On the Item Details Overview page, click View Style
4. Ensure you are on the Raw Data tab of the style page and locate the line of code with the URL that references the styles, usually the second line:For example: https://cdn.arcgis.com/sharing/rest/content/items/d23123ae88a14088843bc552ad3e9868/resources/styles/../sprites/sprite
5. Copy the URL up to “…/resources/” and paste into a new web browser window and add “/export?f=zip” to the end of the URLFor example: https://cdn.arcgis.com/sharing/rest/content/items/d23123ae88a14088843bc552ad3e9868/resources/export?f=zip
6. Download the online resource files when prompted
   
7. Extract the .zip file and inside you will find three folders: info, sprites, and styles
   
   You will use the contents from the downloaded basemap style resources to update your vector tile package contents with the desired style.

Alter your existing .vtpk

You will need file compression software to unzip and then repackage the files within the .vtpk. Not all file compression software will work. I recommend file archiver software 7-Zip, which is free to install and use.

1. Make a copy of the .vtpk and keep the original .vtpk as a fail-safe
2. Right-click on the .vtpk file, click 7-zip from the menu, and click Extract
   • Once the file package is extracted there should be two folders: esriinfo and p12
   • In the p12\resource folder there should be the same folder structure as the downloaded Esri basemap resources folder
     
     
3. Replace the following files from your unzipped .vtpk with those from the downloaded basemap style resources:
   • The root.json file in the info folder
   • All files in the sprites folder
   • The root.json file that is in the styles folder for the one in the downloaded resource, but you need to modify it first
     • Rename the root.json file in the vtpk styles folder and save it as a backup
     • Copy and paste the root.json file from the downloaded resources styles folder into the vtpk styles folder
     • Open both files side by side
     • In the vtpk backup_root.json internal file, you will see that the first lines reference resources in the folder structure; copy those lines
       
       and replace the corresponding lines in the downloaded root.json file
       
       The code highlighted in images above indicate the lines that should be copied and replaced.
   • You have now updated all the files necessary to apply the new style to your vtpk

Create your updated .vtpk

1. Add the two folders into a package file
   • You cannot zip up the parent directory — you must select both the esriinfo and p12 folders, right-click on the selection, click 7-zip, or other compatible file archive software, and click Add to Archive…
     
     
   • Name the file appropriately and type .vtpk as the file extension
   • Select zip as the Archive format
   • 

Special thanks to Tommy Fauvell for his expertise in ArcGIS basemaps. Check out his YouTube channel for more GIS insight.

For more information on vector tile packages and styles visit the following web pages:

• Mapbox Vector Tile Reference
• Esri Story Map: Vector Tile Style, Fonts and Sprites
• Esri Community Post: Why does the basemap change when downloading a mobile map package?