You will learn: how to display a vector basemap with custom styles in a native app.

With the ArcGIS Runtime SDK for Qt you can build mapping applications that use Esri vector basemaps with custom styles. If you don't already have a custom basemap style, you can create a new one with the ArcGIS Vector Tile Style Editor. This application allows you to create a style interactively and then save the style in ArcGIS Online as a portal item. Each portal item has a unique identifier that your application can use to load the style as a layer or a basemap. See Display a map for more details. To learn more about how to create a new custom style with the ArcGIS Vector Tile Style Editor, see the Style a Vector Basemap lab.

In this lab, 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 installed ArcGIS Runtime SDK for Qt and set up your development environment. Please review the install and setup instructions if you have not done this.


Create a new ArcGIS Runtime App Qt Creator Project

  1. Start Qt Creator.

  2. Choose File > New File or Project and select the ArcGIS project template for ArcGIS Runtime {version} Qt Quick app. Give your app a name. For this lab we chose display-a-styled-vector-basemap, but you can choose any name that suits you. Also select the location where your project files should reside on your system. Select Continue.

  3. On the Define Project Details dialog, leave the settings as suggested. Select Continue.

  4. On the Kit Selection dialog, check the kits you previously setup when you installed the SDK. Select Continue.

  5. Verify your selections and select Done.

Add a styled vector tile layer as a basemap

  1. Open the main.qml code file in your project (Resources > qml > qml.qrc > /qml > main.qml). You will update the ApplicationWindow QML component to display a custom basemap. Add a property to define the URL of the vector basemap tile service. Add this to the ApplicationWindow immediately after the title property.

    property string myLayerId: "https://www.arcgis.com/home/item.html?id=d2ff12395aeb45998c1b154e25d680e5"
  2. Alter the template generated code for the Map component to use a ArcGISVectorTiledLayer as the basemap.

        Map {
            Basemap {
                ArcGISVectorTiledLayer {
                    url: myLayerId
  3. Set the initial viewpoint so that the map zooms to the Santa Monica Mountains when the app loads.

            ViewpointCenter {
                Point {
                    x: -118.71511 // longitude
                    y: 34.09042   // latitude
                    SpatialReference { wkid: 4326 } // WGS84
                targetScale: 300000
  4. Run the code and explore the custom national forest and parks vector styles.

Congratulations, you're done!

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


Use your own custom basemap

Complete the lab Style a Vector Basemap and use your own custom basemap instead of the one provided here.

Add layers

Review the lab Create a 2D map with a layer and load the trailheads layer on top of your custom basemap.

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.

Update completed labs

Return to any of your completed ArcGIS DevLabs for Qt and replace the Basemap component with your new custom basemap version.