Skip To Content ArcGIS for Developers Sign In Dashboard


You will learn: how to build an app that displays a vector basemap with custom styles.

Applications can access and display vector tile basemaps and basemaps that have custom styles. You can create your own custom styles with the ArcGIS Vector Tile Style Editor. Custom basemaps are stored as tile layer items in ArcGIS Online or ArcGIS Enterprise. To add the layer to your map, use the item ID to create the vector tile layer, add it to a basemap, and then add the basemap to your application. Additional layers can also be added to a basemap to enhance the visualization. To learn more about how to create your own custom basemap styles, see the Style a vector basemap tutorial.

In this tutorial, you will build a mapping app that loads a custom vector basemap named Forest and Parks Canvas. This basemap emphasizes national forests and parks.

Before you begin

You must have previously installed ArcGIS AppStudio.

Open the starter app project

If you completed the Create a starter app tutorial, start ArcGIS AppStudio and then open your starter app project. Otherwise, complete the tutorial now and open the project.


Declare properties

  1. Run ArcGIS AppStudio. Click your Starter app project in the App Gallery, and then click {;} Edit. This will open your project in Qt Creator.

  2. In the Qt Creator Projects window, double-click MyApp.qml to open it in the editor. In the App declaration, add the following properties to declare the portal where to find the custom basemap style and its item ID.

    property real scaleFactor: AppFramework.displayScaleFactor
    // *** ADD ***
    property string portalUrl: ""
    property string itemID: "d2ff12395aeb45998c1b154e25d680e5"
  3. In the code editor, scroll down to the Map declaration. Use the ArcGISVectorTiledLayer QML type to load a custom vector type style as a basemap layer using its item ID. Update the basemap declaration with the following code:

         Map {
           // *** UPDATE ***
           //BasemapTopographicVector {}
           Basemap {
               ArcGISVectorTiledLayer {
                   url: portalUrl + itemID
  4. In the lower left Sidebar, click Run or press Control-R/Command-R to run the app.

Congratulations, you're done!

Your map should display the custom forest and parks canvas basemap. Compare it to our completed solution project.


Use your own custom basemap

Complete the Style a Vector Basemap tutorial to learn how to use your own custom basemaps.

Add hillshade as a custom basemap layer

Basemaps can contain multiple layers. To enhance the vector styles with terrain, visit ArcGIS Online and find the ID for the World Hillshade layer. It should be 1b243539f4514b6ba35e7d995890db1d.

Use the ArcGISTiledLayer QML type to create the hillshade layer.

    property string hillshadeItemID: "1b243539f4514b6ba35e7d995890db1d"

Create a new basemap by stacking the styled vector tile layer on top of the hillshade tile layer, and change the opacity of the styled tile layer so the hillshade layer is visible.

        Basemap {
            id: customBaseMap
            ArcGISTiledLayer {
                url: portalUrl + hillshadeItemID
            ArcGISVectorTiledLayer {
                url: portalUrl + itemID
                opacity: 0.85

Handle load errors

Custom basemaps may not load in your app for multiple reasons, including network availability, the item's privacy settings, or an incorrect item ID. Add error handling to your app to alert the user if the map does not load and display a message explaining why.

Import Qt Quick Dialogs to show the user an error message:

import QtQuick.Dialogs 1.2

Add a message dialog declaration to App and configure the dialog to be hidden by default.

      MessageDialog {
          id: errorDialog
          title: "Map Error"
          text: "Error text"
          onAccepted: {
          Component.onCompleted: visible = false

Add a load status signal on the Map to catch a failed map load and then show the error dialog with a helpful message:

          onLoadStatusChanged: {
              if (loadStatus === Enums.LoadStatusFailedToLoad) {
                  errorDialog.text = "Could not show custom map " + itemID
                  errorDialog.visible = true